Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Design and Build Your API

Design and Build Your API

Half-day tutorial at ZendCon, talking about the mechanisms and concepts behind creating an awesome API

Lorna Mitchell

October 22, 2012
Tweet

More Decks by Lorna Mitchell

Other Decks in Technology

Transcript

  1. Build Your API

    View full-size slide

  2. About Me
    • Lorna Jane Mitchell
    • Web development consultant
    • API specialist
    • Author, speaker
    • http://lornajane.net

    View full-size slide

  3. The Plan
    • Look at existing APIs
    • HTTP theory and features
    • Consume some APIs
    • How to make a good API

    View full-size slide

  4. What is an API?

    View full-size slide

  5. What is an API?
    • API: Application Programming Interface
    • How we integrate with systems or library
    • On the web: how we exchange data between machines

    View full-size slide

  6. Why Build an API?

    View full-size slide

  7. Why Build an API?
    • To allow users access to data
    • To facilitate integration with other systems
    • For other as-yet-unimagined reasons

    View full-size slide

  8. HTTP
    Web APIs use HTTP. Some key points:
    • Request/response
    • Client/server
    • HTTP headers
    • Data formats
    • Service types

    View full-size slide

  9. Real Examples: Etsy

    View full-size slide

  10. Observations from the Wild
    Formatted URLs:
    • /listings/active
    • /users/:user_id
    • /users/:user_id/shops
    • /shops/:shop_id/listings/active

    View full-size slide

  11. RESTful Services
    REST: REpresentational State Transfer
    A series of concepts
    • everything is a resource
    • resources in a group are called a collection
    • resources have URIs (Unique Resource Identifiers)
    • we perform operations by applying verbs to resources
    • HTTP verbs: GET, POST, PUT, DELETE

    View full-size slide

  12. Service Types
    REST is fashionable!
    RPC (Remote Procedure Call) Services
    • XML-RPC
    • JSON-RPC
    These specify the method name and some parameters
    SOAP

    View full-size slide

  13. RPC Services
    RPC services give method name and parameters
    • Familiar process (we know how to write functions)
    • Can wrap existing functionality

    View full-size slide

  14. Soap
    • Not an acronym
    • (used to stand for Simple Object Access Protocol)
    • Special case of XML-RPC
    • VERY easy to do in PHP
    • Can be used with a WSDL
    • Web Service Description Language

    View full-size slide

  15. Soap Example: Library Class
    public function eightBall() {
    $options = array(
    "Without a doubt",
    "As I see it, yes",
    "Most likely",
    "Reply hazy, try again",
    "Better not tell you now",
    "Concentrate and ask again",
    "Don't count on it",
    "Very doubtful");
    return $options[array_rand($options)];
    }
    /public/soap/Library.php

    View full-size slide

  16. Soap Server
    (don’t blink or you will miss it!)
    include('Library.php');
    $options = array('uri' => 'http://api.local/soap');
    $server = new SoapServer(NULL, $options);
    $server->setClass('Library');
    $server->handle();
    /public/soap/index.php

    View full-size slide

  17. Consuming a Soap Service
    To call PHP directly, we would do:
    include('Library.php');
    $lib = new Library();
    $response = $lib->eightBall();
    echo $response;
    Over Soap:
    $options = array('uri' => 'http://myapi.local',
    'location' => 'http://myapi.local/soap/');
    try{
    $client = new SoapClient(NULL, $options);
    $response = $client->eightBall();
    echo $response;
    } catch (SoapFault $e) {
    echo "ERROR: " . $e->getMessage();
    }

    View full-size slide

  18. Real Examples: Flickr

    View full-size slide

  19. Common Data Types
    • JSON
    • XML
    • and ...

    View full-size slide

  20. JSON
    JSON: JavaScript Object Notation
    • Awesome for JavaScript
    • Native read/write in most other languages
    • No data type information
    • Simple, compact format

    View full-size slide

  21. XML
    XML: eXtensible Markup Language
    • Powerful, verbose format
    • Relatively large data size
    • Preferred by some technology platforms

    View full-size slide

  22. Diversion: cURL
    Curl: Command-line tool for making HTTP requests
    Basic usage: curl [url]
    • -I to see response headers only
    • -v to see request and response headers, and body
    • -X to specify the verb to use
    • -H to send a particular HTTP header
    • -d to send some data

    View full-size slide

  23. Curl Examples

    View full-size slide

  24. Consuming Services from PHP

    View full-size slide

  25. Using File_Get_Contents
    This is the simplest, especially for a GET request
    $response = file_get_contents('http://api.local/');
    var_dump($response);
    You can set more information in the stream context bit.ly/gxBAgV

    View full-size slide

  26. Using Curl
    This extension is commonly available
    $ch = curl_init('http://api.local/');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $response = curl_exec($ch);
    var_dump($response);
    Look out for the CURLOPT_RETURNTRANSFER; without it, this will echo
    the output

    View full-size slide

  27. Using Pecl_HTTP
    This is the most powerful and flexible, and can easily be installed from
    http://pecl.php.net
    $request = new HTTPRequest('http://api.local/', HTTP_METH_GET);
    $request->send();
    $response = $request->getResponseBody();
    var_dump($response);
    Strongly recommend pecl_http if you are able to install pecl modules on
    your platform

    View full-size slide

  28. HTTP Status Codes/Cards

    View full-size slide

  29. HTTP Headers
    Headers are part of the HTTP request/response format, they handle
    additional data.
    Some common headers:
    • Accept and Content-Type: used for content format negotiation
    • User-Agent: to identify what made the request
    • Set-Cookie and Cookie: working with cookie data
    • Authorization: controlling access

    View full-size slide

  30. Real Examples: Accept Headers

    View full-size slide

  31. Real Examples: Github

    View full-size slide

  32. API Authentication

    View full-size slide

  33. API Authentication
    GitHub offers two options
    http://developer.github.com/v3/#authentication
    • Basic auth
    • OAuth token
    • API key is also common

    View full-size slide

  34. Small APIs
    Simple and small makes for a robust API
    • Does all your site functionality need to be duplicated?
    • Will you add every feature you can think of/are asked for?
    KISS! Keep It Simple, Stupid

    View full-size slide

  35. Consistency is Key
    Users don’t read documentation!
    Consistency means that:
    • they can find their way around more quickly
    • they won’t get any nasty surprises
    • they won’t phone you for help

    View full-size slide

  36. Error Handling
    • Always respond in the expected format
    • Use a useful status code
    • Help users to help themselves
    • Be consistent in data validation

    View full-size slide

  37. The Whole Package
    Your API isn’t finished until it has:
    • Documentation! (ideally interactive)
    • Lots of examples and tutorials
    • Other people blogging about it
    • For bonus points: client libraries

    View full-size slide

  38. Choosing the Right Kind of Service
    • Who is the audience?

    View full-size slide

  39. Choosing the Right Kind of Service
    • Who is the audience?
    • technology
    • experience/skills
    • use case

    View full-size slide

  40. Choosing the Right Kind of Service
    • Who is the audience?
    • technology
    • experience/skills
    • use case
    • What will they use it for?
    • Which type of service will you choose?
    • Which data format(s)?

    View full-size slide

  41. Design Your API

    View full-size slide

  42. Build Your API

    View full-size slide

  43. Thanks!
    https://joind.in/6862
    @lornajane
    http://lornajane.net

    View full-size slide