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


  1. Build Your API

  2. About Me • Lorna Jane Mitchell • Web development consultant

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

    and features • Consume some APIs • How to make a good API
  4. What is an API?

  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
  6. Why Build an API?

  7. Why Build an API? • To allow users access to

    data • To facilitate integration with other systems • For other as-yet-unimagined reasons
  8. API Basics

  9. HTTP Web APIs use HTTP. Some key points: • Request/response

    • Client/server • HTTP headers • Data formats • Service types
  10. Real Examples: Etsy

  11. Observations from the Wild Formatted URLs: • /listings/active • /users/:user_id

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

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

    Familiar process (we know how to write functions) • Can wrap existing functionality
  15. 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
  16. 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
  17. 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
  18. 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(); }
  19. Real Examples: Flickr

  20. Data Types

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

  22. JSON JSON: JavaScript Object Notation • Awesome for JavaScript •

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

    Relatively large data size • Preferred by some technology platforms
  24. HTTP

  25. 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
  26. Curl Examples

  27. Consuming Services from PHP

  28. 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
  29. 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
  30. 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
  31. HTTP Status Codes/Cards

  32. 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
  33. Real Examples: Accept Headers

  34. Real Examples: Github

  35. API Authentication

  36. API Authentication GitHub offers two options http://developer.github.com/v3/#authentication • Basic auth

    • OAuth token • API key is also common
  37. A Good API

  38. 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
  39. 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
  40. Error Handling • Always respond in the expected format •

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

  43. Choosing the Right Kind of Service • Who is the

    audience? • technology • experience/skills • use case
  44. 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)?
  45. Design Your API

  46. Build Your API

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