Developing web REST API

Transcript

1. Developing web REST API { "name": "Shalva Usubov", "contact": "@usubov" }
2. Application Programming Interface • Want to scale integration with customers and partners • Need a mobile app • Migrate on Service-oriented architecture • ...
3. • HTTP (methods, status, headers) • REST • Representation • Versioning • Security • Performance • Caching
4. HTTP HyperText Transfer Protocol • Methods • Response status codes • Headers
5. HTTP methods GET fetch a resource representation POST create a resource PUT update a resource PATCH partially update a resource DELETE remove a resource ...
6. 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
8. 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
9. Security Prefer HTTPS • OAuth - most flexible • Basic HTTP Authentication • Custom
10. REST Representational State Transfer Uses URLs to identify resources HTTP verbs indicate the action to perform
11. 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
12. 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
13. 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
14. 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
15. Representation XML, JSON, etc...
16. XML eXtensible Markup Language • Verbose • Includes data type information • Powerful/Complicated
17. XML <photo id="2733" favorite="0" license="3" rotation="90" original format="png"> <owner nsid="12037949754@N01" username="Bees" location="Bedford, UK" /> <title>orford_castle_taster</title> <description>hello!</description> <visibility ispublic="1" isfriend="0" isfamily="0" /> <tags> <tag id="1234" author="12037949754@N01" raw="woo yay">wooyay</tag> <tag id="1235" author="12037949754@N01" raw="hoopla">hoopla</tag> </tags> </photo>
18. JSON JavaScript Object Notation • Widely support in programming languages • Human readable • No data type information
19. 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", } }
20. 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
21. 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
22. HTTP caching Expires for statics content # Response Expires: Sun, 09 Aug 2015 10:56:14 GMT Cache-Control: max-age=36000,public
23. HTTP caching Conditional policy for dynamic content # Response ETag: "f6373f0fd7ccb539c6ec8f5991dddc30" Last-Modified: Wed, 08 Oct 2014 06:32:07 GMT
24. 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
25. 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
26. 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
27. 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
28. 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
29. HTTP caching Last project had over ~75% requests cache hit
30. 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" }
31. Performance • Cache on client and server sides • HTTP compression • Delay async tasks • SPDY/HTTP 2.0 - N+1 over HTTP is expensive
32. 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/
33. Thanks!