Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ae0000/kohana-api

An API module for kohana 3 that accepts and produces xml, json, and x-www-form-urlencoded data. It can easily be extended to support any payload you may need.
https://github.com/ae0000/kohana-api

Last synced: about 2 months ago
JSON representation

An API module for kohana 3 that accepts and produces xml, json, and x-www-form-urlencoded data. It can easily be extended to support any payload you may need.

Awesome Lists containing this project

README 

        
## Kohana-api information ##

###### *Last edited: Wed, 16 July 2010 (stroppytux)* ######

The kohana-api module is meant as a drop in solution for websites needing clients

to be able to have access to the data remotely.

The basic structure behind the API is divided into 4 distinct sections that each

perform an action on the input or output payload. The 4 sections are:



1. #### headers ####

	Requests received from a client contain HTTP/1.1 headers that inform the API

	on what type of payload the request contains and the type of result the client

	expects back. The Api_Header class handles all this information.



2. #### payload ####

	When a client sends a request, the information inside the request is converted

	into a universialy usable payload, and the output that needs to be sent back

	to the client uses the same payload construct. This is handled by the Api_Payload

	class.



3. #### parsers ####

	When the client sends information that needs to be handled, the information

	first get changed into a payload. The payload is then passed to the code that

	will generate the output. The Api_Parser decides on the type of information

	the client sent, then converts that information into a payload using one of

	the parsers defined in the /classes/api/parser/ directory.



4. #### creators ####

	The client has the ability to specify a list of acceptable formats it can

	process by setting the Accept-Type HTTP/1.1 header. If the client specifies

	a format that we have a creator for (located in /classes/api/creators), then

	the Api_Creator will take the output payload and convert it into the format

	to be returned to the client.



### Testing the API ###

When the API is first installed into the modules directory within Kohana, and

you have enabled the module in the /application/bootstrap.php file, you will

have access to the default API controller. This controller just parses information

received from a client, then creates the output information to mirror the input.



A bash script located in `/modules/api/docs/tests` has been created in order to

test the API. Edit the configuration file to point to your server, then run:



* Send an **XML** request to the client receiving **XML** back



		modules/api/docs/tests/api.sh



* Send an **XML** request receiving **JSON** back



		modules/api/docs/tests/api.sh xml 0.8



* Send a **JSON** request receiving **XML** back



		modules/api/docs/tests/api.sh json 0.6



* Send a **GET** request receiving **JSON** back



		modules/api/docs/tests/api.sh get 0.8



The `api.sh` can accept two parameters:



1. #### Request payload ####

	The first parameter is the type of payload you would like to send to the server.

	This can be on of: `xml`, `json`, `post`, or `get`. The payload content is

	defined in the payloads.(xml|json|form). The *GET* and *POST* requests both

	use the payload.form file.



2. #### Response payload ####

	The second parameter contains a numerical value that is passed into the

	Accept-Type header. The Accept-Type has a default value defined as **0.5**

	for the request payload you are sending. If you set the second value to any

	value higher than this, the server will return the payload type set in the

	Accept-Type header.



### Integrating the API ###



The API can be integrated into your own code in many different ways. As an example

I have created a controller called `example.php` that loads a class in the

*/classes/process* directory, then calls methods within that class. The received

payload needs to be nested appropriatly. Any values nested deeper in the request

payload will be passed into the method as parameters.