Cakefest 2010: API Development

API Development
Becoming the Platform
(CakePHP for Back-End Development
or Cake for Web Services)
By Andrew Curioso
CakeFest
2010

Introduction
Yesterday:
Designing CakePHPplug-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’)
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.')';
?>
function beforeFilter()
{
if ( array_key_exists('callback’, $this->params[‘url’]) )
$this->set(‘callbackFunc’, $this->params[‘url’][‘callback’]);
else
$this->set(‘callbackFunc’, false);
}
APP/views/layouts/json/default.ctp
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
Create
curl –d “url=www.example.com” http://tinyr.me/urls.json
Read
curl http://tinyr.me/urls/123.json
Update
curl –d “url=www.example.com/foo” http://tinyr.me/urls/123.json
Delete
curl –X DELETE http://tinyr.me/urls/123.json

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 or PUT 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 request
Invalid ID
404 File Not Found
Success
200 OK
Failure

Delete Method
If not a POST request
Invalid ID
404 File Not Found
Success
200 OK
Failure

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
functionyour_action() {
…
$this->_userError(404);
…
}
APP/controllers/your_controller.php
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 ) ) );
}

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;
}

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.1
Host: www.example.com
POST /urls/123.json HTTP1.1
Host: 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
UrlsController
AmfController
User
POST
::gateway()
::view()
Return data
Format envelope

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

Cakefest 2010: API Development

by Andrew Curioso

Accessibility

Categories

Upload Details

Usage Rights

1 Embed 125

Statistics