Developing web REST API { "name": "Shalva Usubov", "contact": "@usubov" } 

Application Programming Interface ● Want to scale integration with customers and partners ● Need a mobile app ● Migrate on Service-oriented architecture ● ... 

● HTTP (methods, status, headers) ● REST ● Representation ● Versioning ● Security ● Performance ● Caching 

HTTP HyperText Transfer Protocol ● Methods ● Response status codes ● Headers 

HTTP methods GET fetch a resource representation POST create a resource PUT update a resource PATCH partially update a resource DELETE remove a resource ... 

HTTP status codes 200 OK 304 Not Modified 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 500 Internal Server Error 502 Bad Gateway 

No content

HTTP request and response headers Content-Type Content-Language Content-Length Content-Encoding Last-Modified Cache-Control Location ETag Vary Expires If-Modified-Since If-None-Match 

Security Prefer HTTPS ● OAuth - most flexible ● Basic HTTP Authentication ● Custom 

REST Representational State Transfer Uses URLs to identify resources HTTP verbs indicate the action to perform 

REST Method (verbs) URL Description GET /gists Returns all gists POST /gists Create new gist GET /gists/1 Return given gist PATCH /gists/1 Update given gist DELETE /gists/1 Delete given gist 

REST Example GET https://api.github.com/gists POST https://api.github.com/gists GET https://api.github.com/gists/6412448 PATCH https://api.github.com/gists/6412448 DELETE https://api.github.com/gists/6412448 

REST hierarchical association GET https://api.github.com/gists/6412448/commits POST https://api.github.com/gists/6412448/commits GET https://api.github.com/gists/6412448/commits/1 PATCH https://api.github.com/gists/6412448/commits/1 DELETE https://api.github.com/gists/6412448/commits/1 

REST filters, search and pagination GET https://api.github.com/gists?status=regular GET https://api.github.com/gists?public=true GET https://api.github.com/gists?q=something GET https://api.github.com/gists?page=2&per_page=20 

Representation XML, JSON, etc... 

XML eXtensible Markup Language ● Verbose ● Includes data type information ● Powerful/Complicated 

XML orford_castle_taster hello! wooyay hoopla 

JSON JavaScript Object Notation ● Widely support in programming languages ● Human readable ● No data type information 

JSON { "url": "https://api.github.com/gists/6412448", "commits_url": "https://api.github.com/gists/6412448/commits", "id": "6412448", "public": true, "owner": { "login": "shaliko", "id": 36139, "avatar_url": "https://avatars.githubusercontent.com/u/36139?v=2", "url": "https://api.github.com/users/shaliko", } } 

Content Negotiation Client says what formats it can handle, and the server works out what is best Accept: application/json;q=1.0, application/xml;q=0.6 

Versioning Backward compatibility, maintaining multiple versions Accept: application/vnd.github.v3+json https://graph.facebook.com/v1/posts https://graph.facebook.com/v2.1/posts 

HTTP caching Expires for statics content # Response Expires: Sun, 09 Aug 2015 10:56:14 GMT Cache-Control: max-age=36000,public 

HTTP caching Conditional policy for dynamic content # Response ETag: "f6373f0fd7ccb539c6ec8f5991dddc30" Last-Modified: Wed, 08 Oct 2014 06:32:07 GMT 

HTTP caching $ curl -I https://api.github.com/gists/6412448 HTTP/1.1 200 OK Server: GitHub.com Date: Sat, 11 Oct 2014 02:05:35 GMT Content-Type: application/json; charset=utf-8 Status: 200 OK Cache-Control: public, max-age=60 Last-Modified: Thu, 09 Oct 2014 10:58:09 GMT ETag: "82fc020c8b1e99c9562fed6ba56e8230" Content-Length: 2499 Vary: Accept, Accept-Encoding 

HTTP caching $ curl -I https://api.github.com/gists/6412448 HTTP/1.1 200 OK Server: GitHub.com Date: Sat, 11 Oct 2014 02:05:35 GMT Content-Type: application/json; charset=utf-8 Status: 200 OK Cache-Control: public, max-age=60 Last-Modified: Thu, 09 Oct 2014 10:58:09 GMT ETag: "82fc020c8b1e99c9562fed6ba56e8230" Content-Length: 2499 Vary: Accept, Accept-Encoding 

HTTP caching $ curl -I https://api.github.com/gists/6412448 -H 'If-None-Match:" 82fc020c8b1e99c9562fed6ba56e8230"' HTTP/1.1 304 Not Modified Server: GitHub.com Date: Sat, 11 Oct 2014 02:14:37 GMT Status: 304 Not Modified Cache-Control: public, max-age=60 Last-Modified: Thu, 09 Oct 2014 10:58:09 GMT ETag: "82fc020c8b1e99c9562fed6ba56e8230" Vary: Accept, Accept-Encoding 

HTTP caching $ curl -I https://api.github.com/gists/6412448 -H 'If-None-Match:" 82fc020c8b1e99c9562fed6ba56e8230"' HTTP/1.1 304 Not Modified Server: GitHub.com Date: Sat, 11 Oct 2014 02:14:37 GMT Status: 304 Not Modified Cache-Control: public, max-age=60 Last-Modified: Thu, 09 Oct 2014 10:58:09 GMT ETag: "82fc020c8b1e99c9562fed6ba56e8230" Vary: Accept, Accept-Encoding Cut response time 

HTTP caching $ curl -I https://api.github.com/gists/6412448 -H "If-Modified-Since: Thu, 09 Oct 2014 10:58:09 GMT" HTTP/1.1 304 Not Modified Server: GitHub.com Date: Sat, 11 Oct 2014 02:14:37 GMT Status: 304 Not Modified Cache-Control: public, max-age=60 Last-Modified: Thu, 09 Oct 2014 10:58:09 GMT ETag: "82fc020c8b1e99c9562fed6ba56e8230" Vary: Accept, Accept-Encoding 

HTTP caching Last project had over ~75% requests cache hit 

Error handling Code for code, message for people HTTP/1.1 400 Bad Request { "code": 34, "message": "Missing required field", "url": "https://developers.example.com/errors/34" } 

Performance ● Cache on client and server sides ● HTTP compression ● Delay async tasks ● SPDY/HTTP 2.0 - N+1 over HTTP is expensive 

Start from ● RESTful Web Services Cookbook By: Subbu Allamaraju ● Web API Design by Brian Mulloy (apigee) ● http://jsonapi.org ● GitHub API https://developer.github.com/v3/ 

Thanks!