Skip to content

Commit e9d0c49

Browse files
author
Phil Sturgeon
committed
Merge pull request chriskacerguis#126 from jamierumbelow/documentation
Documentation
2 parents 9281924 + 7d816b0 commit e9d0c49

File tree

1 file changed

+131
-10
lines changed

1 file changed

+131
-10
lines changed

‎README.md‎

Lines changed: 131 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -10,17 +10,141 @@ config file and one controller.
1010
1. PHP 5.2+
1111
2. CodeIgniter 2.1.0 to 3.0-dev
1212

13-
Note: for 1.7.x support download v2.2 from Downloads tab
13+
_Note: for 1.7.x support download v2.2 from Downloads tab_
1414

15-
## Usage
15+
## Installation
1616

17-
Coming soon. Take a look at application/controllers/api/example.php for
18-
hints until the default controller demo is built and ready.
17+
Drag and drop the **application/libraries/Format.php** and **application/libraries/REST_Controller.php** files into your application's directories. Either autoload the `REST_Controller` class or `require_once` it at the top of your controllers to load it into the scope. Additionally, copy the **rest.php** file from **application/config** in your application's configuration directory.
1918

20-
I haven't got around to writing any documentation specifically for this project
21-
but you can read my NetTuts article which covers it's usage along with the REST Client lib.
19+
## Handling Requests
2220

23-
[NetTuts: Working with RESTful Services in CodeIgniter](http://net.tutsplus.com/tutorials/php/working-with-restful-services-in-codeigniter-2/)
21+
When your controller extends from `REST_Controller`, the method names will be appended with the HTTP method used to access the request. If you're making an HTTP `GET` call to `/books`, for instance, it would call a `Books#index_get()` method.
22+
23+
This allows you to implement a RESTful interface easily:
24+
25+
class Books extends REST_Controller
26+
{
27+
public function index_get()
28+
{
29+
// Display all books
30+
}
31+
32+
public function index_post()
33+
{
34+
// Create a new book
35+
}
36+
}
37+
38+
`REST_Controller` also supports `PUT` and `DELETE` methods, allowing you to support a truly RESTful interface.
39+
40+
Accessing parameters is also easy. Simply use the name of the HTTP verb as a method:
41+
42+
$this->get('blah'); // GET param
43+
$this->post('blah'); // POST param
44+
$this->put('blah'); // PUT param
45+
$this->delete('blah'); // DELETE param
46+
47+
## Content Types
48+
49+
`REST_Controller` supports a bunch of different request/response formats, including XML, JSON and serialised PHP. By default, the class will check the URL and look for a format either as an extension or as a separate segment.
50+
51+
This means your URLs can look like this:
52+
53+
http://example.com/books.json
54+
http://example.com/books?format=json
55+
56+
Alternatively (and recommend) is using the HTTP `Accept` header, which is built for this purpose:
57+
58+
$ curl -H "Accept: application/json" http://example.com
59+
60+
Any responses you make from the class (see [responses](#responses) for more on this) will be serialised in the designated format.
61+
62+
## Responses
63+
64+
The class provides a `response()` method that allows you to return data in the user's requested response format.
65+
66+
Returning any object / array / string / whatever is easy:
67+
68+
public function index_get()
69+
{
70+
$this->response($this->db->get('books')->result());
71+
}
72+
73+
This will automatically return an `HTTP 200 OK` response. You can specify the status code in the second parameter:
74+
75+
public function index_post()
76+
{
77+
// ...create new book
78+
79+
$this->response($book, 201); // Send an HTTP 201 Created
80+
}
81+
82+
If you don't specify a response code, and the data you respond with `== FALSE` (an empty array or string, for instance), the response code will automatically be set to `404 Not Found`:
83+
84+
$this->response(array()); // HTTP 404 Not Found
85+
86+
## Multilingual Support
87+
88+
If your application uses language files to support multiple locales, `REST_Controller` will automatically parse the HTTP `Accept-Language` header and provide the language(s) in your actions. This information can be found in the `$this->request->lang` object:
89+
90+
public function __construct()
91+
{
92+
parent::__construct();
93+
94+
if (is_array($this->request->lang))
95+
{
96+
$this->load->language('application', $this->request->lang[0]);
97+
}
98+
else
99+
{
100+
$this->load->language('application', $this->request->lang);
101+
}
102+
}
103+
104+
## Authentication
105+
106+
This class also provides rudimentary support for HTTP basic authentication and/or the securer HTTP digest access authentication.
107+
108+
You can enable basic authentication by setting the `$config['rest_auth']` to `'basic'`. The `$config['rest_valid_logins']` directive can then be used to set the usernames and passwords able to log in to your system. The class will automatically send all the correct headers to trigger the authentication dialogue:
109+
110+
$config['rest_valid_logins'] = array( 'username' => 'password', 'other_person' => 'secure123' );
111+
112+
Enabling digest auth is similarly easy. Configure your desired logins in the config file like above, and set `$config['rest_auth']` to `'digest'`. The class will automatically send out the headers to enable digest auth.
113+
114+
Both methods of authentication can be secured further by using an IP whitelist. If you enable `$config['rest_ip_whitelist_enabled']` in your config file, you can then set a list of allowed IPs.
115+
116+
Any client connecting to your API will be checked against the whitelisted IP array. If they're on the list, they'll be allowed access. If not, sorry, no can do hombre. The whitelist is a comma-separated string:
117+
118+
$config['rest_ip_whitelist'] = '123.456.789.0, 987.654.32.1';
119+
120+
Your localhost IPs (`127.0.0.1` and `0.0.0.0`) are allowed by default.
121+
122+
## API Keys
123+
124+
In addition to the authentication methods above, the `REST_Controller` class also supports the use of API keys. Enabling API keys is easy. Turn it on in your **config/rest.php** file:
125+
126+
$config['rest_enable_keys'] = TRUE;
127+
128+
You'll need to create a new database table to store and access the keys. `REST_Controller` will automatically assume you have a table that looks like this:
129+
130+
CREATE TABLE `keys` (
131+
`id` int(11) NOT NULL AUTO_INCREMENT,
132+
`key` varchar(40) NOT NULL,
133+
`level` int(2) NOT NULL,
134+
`ignore_limits` tinyint(1) NOT NULL DEFAULT '0',
135+
`date_created` int(11) NOT NULL,
136+
PRIMARY KEY (`id`)
137+
) ENGINE=MyISAM DEFAULT CHARSET=utf8;
138+
139+
The class will look for an HTTP header with the API key on each request. An invalid or missing API key will result in an `HTTP 403 Forbidden`.
140+
141+
By default, the HTTP will be `X-API-KEY`. This can be configured in **config/rest.php**.
142+
143+
$ curl -X POST -H "X-API-KEY: some_key_here" http://example.com/books
144+
145+
## Other Documentation / Tutorials
146+
147+
* [NetTuts: Working with RESTful Services in CodeIgniter](http://net.tutsplus.com/tutorials/php/working-with-restful-services-in-codeigniter-2/)
24148

25149
## Change Log
26150

@@ -38,8 +162,6 @@ but you can read my NetTuts article which covers it's usage along with the REST
38162
* Separate each piece of the WWW-Authenticate header for digest requests with a comma.
39163
* Added IP whitelist option.
40164

41-
42-
43165
### 2.5
44166

45167
* Instead of just seeing item, item, item, the singular version of the basenode will be used if possible. [Example](http://d.pr/RS46).
@@ -76,7 +198,6 @@ but you can read my NetTuts article which covers it's usage along with the REST
76198
* key => FALSE can now be used to override the keys_enabled option for a specific method, and level is now optional. If no level is set it will assume the method has a level of 0.
77199
* Fixed issue where calls to ->get('foo') would error is foo was not set. Reported by Paul Barto.
78200

79-
80201
## Donations
81202

82203
If my REST Server has helped you out, or you'd like me to do some custom work on it, [please sponsor me](http://pledgie.com/campaigns/8328)

0 commit comments

Comments
 (0)