Permalink
Browse files

Adding copyright stuff and amends to readme

  • Loading branch information...
1 parent bc06737 commit 304d6db6d563bb7485e983b6e6544699370fb642 Neil Crookes committed Jun 1, 2010
Showing with 14 additions and 10 deletions.
  1. +4 −0 models/datasources/rest_source.php
  2. +10 −10 readme.markdown
@@ -2,6 +2,10 @@
/**
* DataSource for interacting with REST APIs
*
+ * @author Neil Crookes <neil@neilcrookes.com>
+ * @link http://www.neilcrookes.com
+ * @copyright (c) 2010 Neil Crookes
+ * @license MIT License - http://www.opensource.org/licenses/mit-license.php
*/
class RestSource extends DataSource {
View
@@ -1,18 +1,18 @@
-CakePHP-ReST-DataSource-Plugin
+CakePHP ReST DataSource Plugin
==============================
A CakePHP Plugin containing a DataSource for interarcting with ReSTful web services.
How it works
------------
- - The Data Source uses CakePHP's HttpSocket class to issue HTTP requests and parse responses.
- - It implements Create, Read, Update and Delete methods, adding the appropriate HTTP verbs into the request if not already set.
- - The response is converted into an array according from the raw response according to the content-type header (XML and JSON currently supported), and the response returned on success (determined by 2xx HTTP response code) or boolean false is returned on failure.
- - In addition, if the request is triggered through a normal model find, save or delete method, and the model has an onError() method, that method will be triggered.
- - The request() method is where all this happens and is called by the CRUD methods, but can also be called directly, and you can pass an object with a request property in the format expected by HttpSocket::request, or an array in the format expected by HttpSocket::request or a string which is a URI.
+ - The DataSource issues HTTP requests through CakePHP's HttpSocket class (default) or your own implementation/extension, e.g. an OAuth enabled HttpSocket http://github.com/neilcrookes/http_socket_oauth, passed in in the constructor.
+ - It implements create, read, update and delete methods, which are called by Model::save(), Model::find() and Model::delete(). These methods expect your Model object to have a request property in the format defined in HttpSocket::request and add the appropriate HTTP verbs into the array if not already set, e.g. POST, GET, PUT, DELETE.
+ - These methods call the public RestSource::request() method passing it an instance of your model object, but you can also access it directly, passing an object with a request property, or an arrayin the format defined in HttpSocket::request or a string which is a URI.
+ - The raw response from the HttpSocket::request() is converted into an array, according to the response's content-type header (XML and JSON currently supported), and the result returned on success (determined by 2xx HTTP response code) or boolean false is returned on failure.
+ - In addition, if the argument to the request() method was an object, the result is also added to a response property of the object, and if the request failed, and the object has an onError() method, that method will be triggered.
-Basic Usage
+Direct Usage
-----------
1. Create a model for each thing on web service you want to interact with. For example create a TwitterStatus model
@@ -41,9 +41,9 @@ Basic Usage
N.B. This example is purely representative and does not include authentication for example, but demonstrate the general idea.
-Advanced Usage
+Other Uses
--------------
-I use this extensively as a base data source which I extend for each web service I need, handling the specifics of each of those web services, such as Authentication, in those classes, by overloading each of the public methods in the Rest datasource as required.
+I abstracted this functionality out of a lot of other datasources I was writing and I use this extensively as a base data source which I extend for each web service I need, handling the specifics of each of those web services, such as Authentication, in those classes, by overloading each of the public methods in the Rest datasource as required.
-For example, you can create a TwitterSource which extends RestSource and overload the request() method, adding in the common request params such as the host key and '.json' on the end of the path key, and the authentication params, then just call parent::request() to handle the issuing of the request and parsing of the response.
+For example, you can create a TwitterSource which extends RestSource and overload the constructor to pass in an instance of my <a href="http://www.neilcrookes.com/2010/04/12/cakephp-oauth-extension-to-httpsocket">HttpSocketOauth extension to CakePHP's HttpSocket</a> class, and the request() method, adding in the common request params such as the host key and '.json' on the end of the path key, and the specific authentication params, then just call parent::request() to handle the issuing of the request and parsing of the response.

0 comments on commit 304d6db

Please sign in to comment.