Cakefest 2010: API Development
Upcoming SlideShare
Loading in...5
×
 

Cakefest 2010: API Development

on

  • 4,005 views

 

Statistics

Views

Total Views
4,005
Views on SlideShare
3,844
Embed Views
161

Actions

Likes
5
Downloads
70
Comments
0

1 Embed 161

http://andrewcurioso.com 161

Accessibility

Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment
  • Who am I.Introduce myVBO.About this presentation.What I’ll talk about.
  • Neil – plugins to consumeNot much code.Overview.All the slides will be online right after lunch.
  • Raise your hand up if you use CakePHP to handle some kind of data.Now put your hand down if you don’t have an API.If you have info why not be a platform?It doesn’t matter if the platform is very simple. A blog is a platform. It has an API for posting new articles and it has an RSS feed for syndicating them.Now that I simplified it.That’s my take.
  • Even if you are developing a closed API…I hope everyone considers open APIs.All this roles up into one concept. “The platform play.” So if you need something to go back to your boss or your investors with… that’s the thing. You’re making a platform play.
  • If this was five years ago...But the strategy works pretty well. TwitterFacebookBit.lyAmazonandSalesforceNow it is almost a necessity to have an API of some sort.
  • There are multiple patterns for APIs. There are a couple more lesser used ones but the two big ones are REST and RPC.Within those patterns you can use one or more formats to transfer your data.
  • Rest stands for Representational State Transfer incase you missed it in Neal’s presentation. As mentioned yesterday, the largest example of REST in the wild is HTTP.Luckily for us, CakePHP is usually layered on-top of HTTP so it inherits all the RESTful mechanisms.REST has a concept called resources (a specific user or comment are two examples).They are also called nouns which are acted on by verbs.There are five verbs in HTTP. We will focus on three.Finally, one last important thing… CakePHP makes REST easy.
  • The app that I will be using as an example today is the simplest app that I could think of.It is a URL shortening services that allows you to authenticate and thus be able to delete and edit URLs that you yourself shortened, and also basic CRUD.
  • There are two models. The user model, which is pretty standard for a CakePHP project, and the urls model which I have on the screen.A full URL shortened can, of course, get much more complicated than that. But for today I’m keeping it basic.
  • Once you’ve baked your model and what not you can open up your router and map the resource. This will register all the routes you need for REST in one call.You can still do it manually if you want but you don’t have to.These are the six routes registered when you map a resource.
  • One rule to live by is to never write or delete data on anything that is not a POST, PUT, or DELETE request.The main purpose of this rule is to protect against Cross Site Request Forgeries or CSRF attacks which are every difficult to defend against otherwise.Say that the add method accepted GET requests. Someone could then simply embed an image on a page with the add URL as a source and execute a add() as any user who visits the site.
  • Before we begin developing views we’ll haveto tell PHP to recognize file extensions and switch the views and layouts accordingly.We do this by turning on parseExtensions in the routes.php file and including the RequestHandler component in the app_controller.The RequestHandler component is what actually switches the views. It also includes helpers automatically in the view if a helper has the same name as the extension (like XML) and parses incoming POSTed XML and assigns it to the data property of the controller.
  • We now need to create a couple views.The Json view is the first and the one that I like the most. Because it is simple and easy to understand.It is fast thanks to native PHP support, and also very wide-spread.What you see here is the entire view for the view action in the urls controller.Notice the path to the view. The RequestHandler will tell Cake to look in the json folder for the appropriate view.
  • We can also easily support JsonP or Json with padding.JsonP specifies a Javascript callback function to execute with the results of a request.It allows for cross domain requests because you can trigger it via a simple script-include and function calls works across domains so the callback will work just fine.One important note is that it is only for GET requests. So, as I said earlier, it shouldn’t be able to write or delete data.JsonP can be handle generically in the layout. Notice the layout path.A JsonP request always takes the callback via a query parameter. So your app controller can read in the callback then set it for use in the view. The layout then reads it sand wraps the output in it is necessary.
  • Now for the XML view. And I can hear the boos now.XML does have some benefits. It is strongly typed, human readable, and has lots of existing tools available.Like Json, the view is pretty self-explanatory. Note the xml sub-directory in the view path.
  • One of the best parts about using parseExtensions and RequestHandler is you can literally have as many views as you want into the data.I listed just some of them here.
  • Erik’s talk.
  • If you did the ACL stuff Erik was talking about…Little difficult. Default behavior is redirectController, model, and object
  • Maintenance mode

Cakefest 2010: API Development Cakefest 2010: API Development Presentation Transcript

  • 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
    405 Method Not Allowed
    Invalid ID
    404 File Not Found
    Success
    200 OK
    Failure
    200 OK with explanation
  • Delete Method
    If not a POST 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
    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 ) ) );
    }
    APP/app_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.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