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

More Decks by Lorna Mitchell

Other Decks in Technology


  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