Design and Build Your API

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

Transcript

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 audience?
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