Embed Size (px)
DESCRIPTION
Citation preview
API Development
Becoming the Platform(CakePHP for Back-End Developmentor Cake for Web Services)By Andrew Curioso
CakeFest2010
Introduction
Yesterday: Designing CakePHP plug-ins for
consuming APIs Today:
Create your own API▪ Basic setup▪ Extras
Become a platform
Be “a” platform A blog is a platform
Become a platform
Internal only (closed) Multi-platform
(consumers) Scalable
External (open) Everything + Growth▪ Mash-ups!▪ Innovation▪ Evangelists
“The Platform Play”
Who’s already a platform Google Facebook Digg Twitter Yahoo BOSS /
Flickr / Delicious / etc.
Salesforce Ebay Amazon
Gowalla FourSquare Bit.ly Paypal Authorize.net Etc…
Types of APIs
PATTERNS
Representation State Transfer (REST)
Remote Procedure Calls (RPC)
PROTOCOLS / FORMATS XML JSON YAML AMF Etc...
RESTful
Representational State Transfer Resource based (nouns) 5 verbs
GET PUT POST DELETE HEAD
Easy in CakePHP
Today’s App
URL shortening website User authentication (simple) Create, read, update, and delete (CRUD)
Models
id user_id url created modified
users urls
Making it RESTful
APP/config/routes.php Router::mapResource(‘users’)
Verb URL Controller Method
GET /users.json UsersController::index()
GET /user/123.json UsersController::view(123)
POST /users.json UsersController::add()
PUT /users/123.json UsersController::edit(123)
DELETE /users/123.json UsersController::delete(123)
POST /users/123.json UsersController::edit(123)
Source: http://book.cakephp.org/view/1239/The-Simple-Setup
Security Pitfall
Only you can prevent CSRF Only POST and PUT should write data Only POST and DELETE should delete
data
Mapping Extensions
Router::parseExtensions() RequestHandler component
Switches layouts / views Includes helpers Parses incoming XML on POST
Router::connect( "/:controller/:id”, array ("action" => "edit", "[method]" => "PUT"), array("id" => "[0-9]+”));
Source: http://book.cakephp.org/view/1240/Custom-REST-Routing
Json View
Simple Fast Wide-spread
<?php echo json_encode( $url );?>
APP/views/urls/json/view.ctp
JsonP
P w/ padding Uses callback Cross domain
<?php if ( $callbackFunc !==
false ) echo $callbackFunc.'(';
echo $content_for_layout;
if ( $callbackFunc ) echo $callbackFunc.')'; ?>
APP/views/layouts/json/default.ctp
function beforeFilter(){
if ( array_key_exists('callback’, $this->params[‘url’]) ) $this->set(‘callbackFunc’, $this->params[‘url’]
[‘callback’]);
else $this->set(‘callbackFunc’, false);
}
APP/app_controller.php
XML View
Strongly Typed Human readable Lots of existing tools
<? echo ‘<url>’; echo $xml->serialize( $url ); echo ‘<url>’;?>
APP/views/urls/xml/view.ctp
Other Views
HUMAN READABLE
XML Json / JsonP HTML YAML CSV Serialized PHP Etc…
BINARY
AMF Microsoft Excel PDF JPEG / PNG Etc…
Testing It Out Using cURL
curl –d “url=www.example.com” http://tinyr.me/urls.json
Create
curl http://tinyr.me/urls/123.json
Read
curl –d “url=www.example.com/foo” http://tinyr.me/urls/123.json
Update
curl –X DELETE http://tinyr.me/urls/123.json
Delete
Done?
WE HAVE
MVC files RESTful Views
XML Json / JsonP
WE’RE MISSING
Error handling Pagination Authentication Authorization Documentation
Status Codes
Success 200 OK * 201 Created * 303 See Other *
Error 401 Unauthorized * 402 Payment
Required 403 Forbidden * 404 Not Found *
Error (continued) 405 Method Not
Allowed * 409 Conflict 410 Gone 500 Internal Server
Error 501 Not Implemented 503 Service
Unavailable
Add Method
If not a POST request 405 Method Not Allowed
Already existed 303 See Other
Save success 201 Created
Failure 200 OK with explanation
Edit Method
If not a POST or PUT request 405 Method Not Allowed
Invalid ID 404 File Not Found
Success 200 OK
Failure 200 OK with explanation
Delete Method
If not a POST or DELETE request 405 Method Not Allowed
Invalid ID 404 File Not Found
Success 200 OK
Failure 200 OK with explanation
Global
User is not allowed to access resource 403 Forbidden
User is not logged in 401 Unauthorized
Throwing Errors
Same format Descriptive
Human Computer
Comprehensive
Implementation
function your_action() { … $this->_userError(404); …}
function _userError( $code, $options=array() ) { $codes = array( 402 => 'Payment Required', … ); $this->header("HTTP/1.1 {$type} {$codes[$type]}"); $this->cakeError('error'.$type, array( array( 'options' => $options ) ) );}
APP/app_controller.php
APP/controllers/your_controller.php
Implementation
{"Error": { "code" : 404, "description" : "File Not Found"}}
APP/views/errors/error404.ctp
HTTP Headers
Return meta-information Rate limiting Pagination Etc.
Pagination
Uses HTTP headers App defined start with “X-”
function paginate($object=NULL, $scope=array(), $whitelist=array() ) { $data = parent::paginate($object,$scope,$whitelist);
// … messy code to get the object …
$this->header('X-Current-Page: '.((int)$this->params['paging'][$object->alias]['page'])); $this->header('X-Page-Limit: '.((int)$this->params['paging'][$object->alias]['options']
['limit'])); $this->header('X-Page-Total: '.((int)$this->params['paging'][$object->alias]['count']));
return $data;}
APP/app_controller.php
Multi-Platform Dev
Use a UI that makes sense Bring something to the table
Platform Support
WEB BROWSERS
Do not support: DELETE PUT
FORTUNATELY CAKE…
Let’s you do this:
_method=DELETE
Platform Support
DELETE /urls/123.json HTTP1.1Host: www.example.com
POST /urls/123.json HTTP1.1Host: www.example.com
_method=DELETE
Authentication
Authorization
There is no magic One or more:
user_id Administrator Moderator
Documentation
Vocabularies / Schemas DTD or schema files
Examples Code I/O
Community Feedback
What about SOAP and AMF?
CakePHP rocks with REST SOAP is heavy AMF is light but requires Flash But, if you still want to, you can
Flow for SOAP and AMF
Example Flow
Router AmfController UrlsController
::gateway()
::view()
Return data
Format envelope
User
POST
Some final words…
Don’t Choose
Views are easy
API Developers Checklist
Documentation Example code
Definition files (if applicable) Unit tests
Finding the code
MIT License http://tinyr.me
Happy Aniversary
Happy anniversary, Laura. 1 year: Sept. 5, 2010
Andrew Curioso
Contact: www.AndrewCurioso.com/contact @AndrewCurioso on Twitter
