Design and Build Your API

Slide 1

Slide 1 text

Build Your API

Slide 2

Slide 2 text

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

Slide 3

Slide 3 text

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

Slide 4

Slide 4 text

What is an API?

Slide 5

Slide 5 text

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

Slide 6

Slide 6 text

Why Build an API?

Slide 7

Slide 7 text

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

Slide 8

Slide 8 text

API Basics

Slide 9

Slide 9 text

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

Slide 10

Slide 10 text

Real Examples: Etsy

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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 Identiﬁers) • we perform operations by applying verbs to resources • HTTP verbs: GET, POST, PUT, DELETE

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

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

Slide 17

Slide 17 text

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

Slide 18

Slide 18 text

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(); }

Slide 19

Slide 19 text

Real Examples: Flickr

Slide 20

Slide 20 text

Data Types

Slide 21

Slide 21 text

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

Slide 22

Slide 22 text

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

Slide 23

Slide 23 text

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

Slide 24

Slide 24 text

HTTP

Slide 25

Slide 25 text

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

Slide 26

Slide 26 text

Curl Examples

Slide 27

Slide 27 text

Consuming Services from PHP

Slide 28

Slide 28 text

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

Slide 29

Slide 29 text

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

Slide 30

Slide 30 text

Using Pecl_HTTP This is the most powerful and ﬂexible, 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

Slide 31

Slide 31 text

HTTP Status Codes/Cards

Slide 32

Slide 32 text

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

Slide 33

Slide 33 text

Real Examples: Accept Headers

Slide 34

Slide 34 text

Real Examples: Github

Slide 35

Slide 35 text

API Authentication

Slide 36

Slide 36 text

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

Slide 37

Slide 37 text

A Good API

Slide 38

Slide 38 text

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

Slide 39

Slide 39 text

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

Slide 40

Slide 40 text

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

Slide 41

Slide 41 text

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

Slide 42

Slide 42 text

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

Slide 43

Slide 43 text

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

Slide 44

Slide 44 text

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