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. About Me • Lorna Jane Mitchell • Web development consultant

    • API specialist • Author, speaker • http://lornajane.net
  2. The Plan • Look at existing APIs • HTTP theory

    and features • Consume some APIs • How to make a good API
  3. What is an API? • API: Application Programming Interface •

    How we integrate with systems or library • On the web: how we exchange data between machines
  4. Why Build an API? • To allow users access to

    data • To facilitate integration with other systems • For other as-yet-unimagined reasons
  5. HTTP Web APIs use HTTP. Some key points: • Request/response

    • Client/server • HTTP headers • Data formats • Service types
  6. Observations from the Wild Formatted URLs: • /listings/active • /users/:user_id

    • /users/:user_id/shops • /shops/:shop_id/listings/active
  7. 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
  8. Service Types REST is fashionable! RPC (Remote Procedure Call) Services

    • XML-RPC • JSON-RPC These specify the method name and some parameters SOAP
  9. RPC Services RPC services give method name and parameters •

    Familiar process (we know how to write functions) • Can wrap existing functionality
  10. 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
  11. 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
  12. 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
  13. 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(); }
  14. JSON JSON: JavaScript Object Notation • Awesome for JavaScript •

    Native read/write in most other languages • No data type information • Simple, compact format
  15. XML XML: eXtensible Markup Language • Powerful, verbose format •

    Relatively large data size • Preferred by some technology platforms
  16. 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
  17. 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
  18. 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
  19. 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
  20. 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
  21. 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
  22. 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
  23. Error Handling • Always respond in the expected format •

    Use a useful status code • Help users to help themselves • Be consistent in data validation
  24. 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
  25. Choosing the Right Kind of Service • Who is the

    audience? • technology • experience/skills • use case
  26. 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)?