Designing CakePHP plugins for consuming APIs

Designing CakePHP plugins for consuming APIsBy @neilcrookes for CakeFest2010www.neilcrookes.comgithub.com/neilcrookes

ContentsFoundationsCakePHP plugins, APIs, REST, HTTP, CakePHP HttpSocket, OAuthDesign approachTraditional approach, issues with that, my solutionExamples

Types of CakePHP pluginsMini appsProvide full functionality you can include in your app e.g. blog, store locatorExtendersExtend your app with more functionality e.g. commentable & taggableEnhancersEnhance your apps existing functionality e.g. filterWrappersProvide functionality to access 3rd party APIs

APIsSource: http://www.programmableweb.com/apis 73% of all APIs (listed on ProgrammableWeb) are RESTful

My work so far has been mainly consuming RESTful APIs so this presentation and examples will focus on REST

But concepts illustrated in the design approach section later on can be applied to any protocolQuick intro to RESTREspresentational State Transfer“The largest known implementation of a system conforming to the REST architectural style is…” http://en.wikipedia.org/wiki/Representational_State_TransferThe World Wide WebClients and servers communicating via HTTPUses existing HTTP verbs (GET, POST etc)Acts on a resource (URI)

HTTPSend request<HTTP verb> <URI> HTTP/1.1<Header 1 name>: <Header 1 value>...<optional body>You’ll get some kind of response (hopefully)HTTP/1.1 <Status Code> <Status Message><Header 1 name>: <Header 1 value>...<optional body>

Simple HTTP GET Request & ResponseRequestGET http://www.example.com/index.html HTTP/1.1User-Agent: My Web BrowserResponseHTTP/1.1 200 OKContent-Type: text/htmlContent-Length: 70<html><head><title>My Web Page</title></head><body><h1>My Web Page</h1></body></html>

Simple HTTP POST Request & ResponseRequestPOST http://www.example.com/login HTTP/1.1Content-Type: application/x-www-form-urlencodedContent-Length: 38username=neilcrookes&password=abcd1234ResponseHTTP/1.1 301 Moved PermanentlyLocation: http://www.example.com/my_account

CakePHP’s HttpSocket Classcake/libs/http_socket.phpUsage: App::import(‘Core’, ‘HttpSocket’); $Http = new HttpSocket(); $response = $Http->request(array( ‘method’ => ‘POST’, ‘uri’ => array( ‘host’ => ‘example.com’, ‘path’ => ‘login’), ‘body’ => array( ‘username’ => ‘neilcrookes’, ‘password’ => ‘abcd1234’)));See HttpSocket::request property for defaults HttpSocketHandles creating, writing to and reading from sockets (because it extends CakeSocket)Constructs HTTP escaped, encoded requests from array parameters you send itParses HTTP response from the server intoStatusBodyCookiesCan handle Basic Auth (username:password@)

OAuthIn summary, it allows users of a service (e.g. Twitter) to authorize other parties (i.e. your application) access to their accounts on that service, without sharing their password with the other parties.In reality, it means:a little bit of handshaking between your app and the service provider to get various string tokensredirecting the user to the service in order for them to authorize your app to access their account, so the user only signs in to the service, not your app.the service provides you with a token you can persist and use to make authorized requests to their service on behalf of the userIn practice it’s just an extra header line (Authorization header) in the HTTP request which containssome arbitrary parameters e.g. timestampa token that identifies your application to the API providera signature string that signs the request and is a hash of various request parameters and the secret tokens you retrieved aboveUsed by e.g. Twitter & Google APIs

HttpSocketOauthUsage example to tweet “Hello world!”:App::import('Vendor', 'HttpSocketOauth');$Http = new HttpSocketOauth();$response = $Http->request(array( 'method' => 'POST', 'uri' => array( 'host' => 'api.twitter.com', 'path' => '1/statuses/update.json'), 'auth' => array( 'method' => 'OAuth', 'oauth_token' => <oauth token>, 'oauth_token_secret' => <oauth token secret>, 'oauth_consumer_key' => <oauth consumer key>, 'oauth_consumer_secret' => <oauth consumer secret>), 'body' => array( 'status' => 'Hello world!')));http://www.neilcrookes.com/2010/04/12/cakephp-oauth-extension-to-httpsocket/http://github.com/neilcrookes/http_socket_oauth

Traditional approach: DataSourceComplex DataSource containing all the logicCall methods on the DataSource directly from your models or controllersor as implied by the example Twitter DataSource in the cook book: access DataSource methods through your models but include most of the logic in the DataSourcehttp://book.cakephp.org/view/1077/An-ExampleWorks well for simple stuffThis is how I started implementing

However...Does not scale well for large APIsTwitter has ~100 API calls available, all with a wide variety of options and parameters. The cook book Twitter DataSource partially implements 2 API calls and is 86 linesDoes not exploit built-in CakePHP goodnessCallbacksValidationPaginationDoes not allow for multiple models (and therefore multiple schemas) to use the same DataSourceDidn’t feel right to me

So what does feel right?What operations are we actually doing?Reading dataCreating and updating dataDeleting datai.e. Find, save & deleteWhat type of classes in CakePHP provide these methods?

ModelsPhoto by memoflores, available under creative commonshttp://www.flickr.com/photos/memoflores/And what should models be?...

FAT!Photo by cstreetus, available under creative commonshttp://www.flickr.com/photos/cstreetus/Sorry but every other image I found through searching for “fat models” or “fat ladies” was completely inappropriate ;-)

So if we move our API calls into Model::find(), Model::save() and Model::delete() methodsIt feels like the right placeWe’re more familiar with interacting with theseWe can have lots of simple models classes to achieve scale, separation of concerns and different models can have different validation rules and schemas and we can collect them together in a pluginBut...

But what about CakePHP goodness?Triggering callbacksbeforeFind(), afterFind(), beforeSave(), afterSave(), beforeValidate(), beforeDelete(), afterDelete()Triggering validationHandling custom find typesIf we made the API calls directly in these methods and returned the response, to exploit this excellent built-in additional CakePHP functionality we’d have to trigger/code them manuallyWe’d be duplicating loads of code from CakePHP’s core Model class.Not very DRY

To understand the solution, we must understand CakePHP Model internalsModel methods like find(), save() and delete() accept various params such as conditions, data to save etcHandle custom find types for find() onlyHandle validation for save() onlyTrigger the before*() callbacksCall create(), read(), update() or delete() on that model’s DataSourceTrigger the after*() callbacksReturn the result

So what’s my solution for designing CakePHP plugins for consuming APIs?Plugin containing one model for each type of resource in the API e.g. TwitterStatus or YouTubeVideoModels implement find() (or actually more commonly just CakePHP custom find types), save() and delete() methods as appropriateThese methods set the details of the request, i.e. The array that represents an HTTP request that HttpSocket::request() methods expects (as we saw earlier in this presentation) in a request property of your model, then calls the same method on the parent object i.e. Model.Cont...

Solution continuedCakePHP Model class handles validation and custom find types, triggers callbacks etc then calls create(), read(), update() or delete() on the child model’s (your model’s) DataSource, and passes the model objectYour model’s useDbConfig property should be set to a custom DataSource that you also include in your pluginYour DataSource implements the appropriate CRUD method(s) and issues the API call described in the model’s requestproperty, and returns the results

Hmmm, sounds complicatedIt’s notI’ve written a REST DataSource you can use (see later)All you have to do is create a model that has find() or save() methods, in which you set a request property to an array expected by HttpSocket::request() and call the same method on the parent.

E.g. Creating a tweet<?phpclass TwitterStatus extends AppModel { public function save($data = null) { $this->request = array( 'uri' => array( 'host' => 'api.twitter.com', 'path' => '1/statuses/update.json'), 'body' => array( 'status' => $data['TwitterStatus']['text'])); return parent::save($data); }}?>

Which you call like thisClassRegistry::init('Twitter.TwitterStatus')->save(array( 'TwitterStatus' => array( 'text' => “Hello world!”)));... from anywhere you like in your CakePHP application, e.g. In your Post model afterSave() method, thus automatically creating a tweet every time you create a new post.

RestSourcehttp://www.neilcrookes.com/2010/06/01/rest-datasource-plugin-for-cakephp/http://github.com/neilcrookes/CakePHP-ReST-DataSource-PluginYou can set your model’s useDbConfigparam to this DataSource, or you can write your own DataSource that extends this oneE.g. Override RestSource::request() to add in the host key in the $model->request property if it’s the same for all API calls, then call parent::(request)

This diagram illustrates the flow through the methods an classes involved in creating a tweethttps://docs.google.com/drawings/edit?id=1Aht7huICl9bhl2hWRdM0VdoaBePpJ0kXkceyQpAR8os&hl=en_GB&authkey=CISSqJkN

In summaryBy designing plugins like this you’re providingSimple (1 line) method calls to API functionsThat are familiar to all CakePHP bakersAnd easy to documentYou also get to exploit CakePHP goodness such as validation and callbacks etcYou can have multiple models, one for each resource type on the API, each with it’s own schema (which the FormHelper uses) and validation rules

Uploading a YouTube Video – you doClassRegistry::init('Gdata.YouTubeVideo')->save(array( 'YouTubeVideo' => array( 'title' => 'Flying into Chicago Airport', 'description' => 'Filmed through the plane window coming in over the lake', 'category' => 'Travel', 'keywords' => 'Chicago, Plane, Lake, Skyline', 'rate' => 'allowed', 'comment' => 'allowed', 'commentVote' => 'allowed', 'videoRespond' => 'allowed', 'embed' => 'allowed', 'syndicate' => 'allowed', 'private' => 1, 'file' => array( 'name' => 'chicago 1 060.AVI', 'type' => 'video/avi', 'tmp_name' => 'C:indowsemphp6D66.tmp', 'error' => 0, 'size' => 5863102))));

Uploading a YouTube Video – plugin createsPOST /feeds/api/users/default/uploads HTTP/1.1Host: uploads.gdata.youtube.comConnection: closeUser-Agent: CakePHPContent-Type: multipart/related; boundary="Next_Part_4c801b22-52e8-4c70-961b-0534fba3b5b1“Slug: chicago 1 060.AVIGdata-Version: 2X-Gdata-Key: key=<my developer key>Authorization: OAuth oauth_version="1.0",oauth_signature_method="HMAC-SHA1",oauth_consumer_key="anonymous",oauth_token=“<my oauth token>",oauth_nonce="fa4b6fc350e19f675f2e5660657e643c",oauth_timestamp="1283463971",oauth_signature="3fIXJ%2BmdV6KLk4zJYszR7M90lIg%3D“Content-Length: 5864289--Next_Part_4c801b22-52e8-4c70-961b-0534fba3b5b1Content-Type: application/atom+xml; charset=UTF-8<?xml version="1.0" encoding="utf-8"?><entry xmlns="http://www.w3.org/2005/Atom" xmlns:media="http://search.yahoo.com/mrss/" xmlns:yt="http://gdata.youtube.com/schemas/2007"> <media:group> <media:title type="plain">Flying into Chicago Airport</media:title> <media:description type="plain">Filmed through the plane window, shows coming in over the lake</media:description> <media:category scheme="http://gdata.youtube.com/schemas/2007/categories.cat">Travel</media:category> <media:keywords>Chicago, Plane, Lake, Skyline</media:keywords> <yt:private/> </media:group> <yt:accessControl action="rate" permission="allowed"/> <yt:accessControl action="comment" permission="allowed"/> <yt:accessControl action="commentVote" permission="allowed"/>< <yt:accessControl action="videoRespond" permission="allowed"/> <yt:accessControl action="embed" permission="allowed"/> <yt:accessControl action="syndicate" permission="allowed"/></entry> --Next_Part_4c801b22-52e8-4c70-961b-0534fba3b5b1 Content-Type: video/aviContent-Transfer-Encoding: binary<binary file data>

Designing CakePHP plugins for consuming APIs

Related slideshows

Recommended for you

Recommended for you

Recommended for you

Recommended for you

Recommended for you

Recommended for you

Recommended for you

Recommended for you

More Related Content

What's hot

What's hot (20)

Similar to Designing CakePHP plugins for consuming APIs

Similar to Designing CakePHP plugins for consuming APIs (20)

Recently uploaded

Recently uploaded (20)

Designing CakePHP plugins for consuming APIs