Design and implementation of Web APIs

Session presented at the 41th meeting of the NetPonto community, September 2013

Transcript

1. Design and implementation of Web APIs Pedro Félix http://netponto.org 41ª Reunião Presencial - 21/09/2013
2. Pedro Félix Teacher at ISEL and member of the CCISEL R&D center Consultant Rupeal SAPO – Service Delivery Broker Web API Advisory Board member Co-author of the upcoming book “Designing Evolvable Web APIs with ASP.NET” to be published by O’Reilly
3. Agenda • Web APIs • The architecture of the Web • The HTTP protocol • Internet Media Types • Hypermedia
4. Web APIs • Application Programming Interfaces • Exposed on the Web • Using HTTP as the application protocol • Accessible by multiple client types – E.g. Mobile devices • A.K.A: HTTP APIs, HTTP services, RESTful services
5. Web APIs Source: http://blog.programmableweb.com/2012/02/06/5000-apis-facebook-google-and-twitter-are-changing-the-web/
6. Web APIs Source:http://blog.programmableweb.com/2012/11/26/8000-apis-rise-of-the-enterprise/
7. Why APIs? • Multi-platform support (“4 screens”) • API as a Product – http://www.twilio.com • Extend products and partner opportunities – http://bluevia.com • Improve functionality – http://developer.github.com/ – http://developers.facebook.com/docs/reference/api/
8. Example: Google API Console
9. API Types Server Client
10. API Types Server Client
11. API Types Server Client
12. API Types Server Client Client Client
13. API Types Server Client Client Client Server Server
14. Web APIs • Application Programming Interfaces • Exposed on the Web • Using HTTP as the application protocol • Accessible by multiple client types – E.g. Mobile devices
15. The Architecture of the Web
16. The Architecture of the Web • “The World Wide Web (WWW, or simply Web) is an information space in which the items of interest, referred to as resources, are identified by global identifiers called Uniform Resource Identifiers (URI).” • “ (…) the three architectural bases of the Web that are (…) – Identification (…) – Interactions (…) – Formats (…)” In http://www.w3.org/TR/2004/REC-webarch-20041215/
17. The Architecture of the Web Resource User-Agent Representation Uniform Resource Identifier Format
18. The Architecture of the Web • Identification – URIs • http://www.ietf.org/rfc/rfc2616.txt • Interaction – Protocols • HTTP, SMTP • Representations and formats – Media types: • text/html, application/xml, application/json, image/png, audio/mpeg, application/atom+xml, … – IANA media type registry at • http://www.iana.org/assignments/media-types
19. Web API design • Use HTTP as an application protocol – Method semantics – Content-negotiation – Caching – Concurrency – Fault tolerance – Security
20. HTTP Messages Method Target Request Metadata Metadata Representation Resource Status Code Response Metadata Metadata Representation Request Message Response Message
21. Uniform interface • GET – obtain a representation for the target resource • PUT – define a resource state (create or update) • PATCH – partially update a resource (RFC 5789) • DELETE – delete a resource • POST – processing of the enclosed request representation by the target resource
22. Uniform interface • HEAD – Similar to GET but without the representation body • OPTIONS – Obtain the communication options available for the target resource • TRACE – Obtain a Loop-back • “Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content” - http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics-22
23. Uniform interface • Method properties – Safety – Idempotency • Uniform interface – Closed and uniform set of methods – Independent of resources – Contrasts with OOP – specific methods per type – Visibility – Using controller resources to operate on other resources
24. Status codes • Successful – 200 OK – 201 Created – 202 Accepted – 204 No Content – ... • Redirection – 300 Multiple Choices – 301 Moved Permanently – 302 Found – 304 Not Modified – 303 See Other – ... • Client Error – 400 Bad Request – 403 Forbidden – 404 Not Found – 405 Method Not Allowed – 406 Not Acceptable – 409 Conflict – ... • Server Error – 500 Internal Server Error – 502 Bad Gateway – 503 Service Unavailable – ...
25. 200 OK GET Example: asynchronous job /jobs/1 POST 202 Accepted /instances/123 GET /results/456 303 See Other GET 200 OK 200 OK
26. Representations and media types • application/octet-stream • text/plain • text/csv • application/xml, application/json • text/html • text/calendar • image/gif
27. Example: application/api-problem+json { "problemType": "http://example.com/probs/out-of-credit", "title": "You do not have enough credit.", "detail": "Your current balance is 30, but that costs 50.", "problemInstance": "http://example.net/account/12345/msgs/abc", "balance": 30, "accounts": ["http://example.net/account/12345", "http://example.net/account/67890"] } In http://tools.ietf.org/html/draft-nottingham-http-problem-04
28. Content negotiation • Accept request header – Expresses client preferences – Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 – Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3 – Accept-Language: en-US,en;q=0.8,pt-PT;q=0.6 • Server-driven negotiation – Server chooses representation • Client-driven negotiation – 300 Multiple Choices – Multiple representations with specific identifiers
29. Caching • Expiration-based caching – Origin-server defines representation validity – Intermediaries can serve the representation while it is valid R R R Cache-Control Cache-Control Age, Warning R age Cache-Control Revalidation R
30. Caching • Cache-Control header (both requests and responses) – Requests • no-cache, no-store • max-age, max-stale, min-fresh – Response • public, private • no-cache, no-store • must-revalidate • max-age, s-maxage • Extensions: stale-while-revalidate, stale-if-error • Warning header – 110 Response is Stale – 111 Revalidation Failed
31. Conditional Requests • Two goals – More efficient cache revalidation – Optimistic concurrency control • Validators – Last-Modified – Etag (entity-tag – opaque identifier)
32. Hypermedia “Hypermedia is defined by the presence of application control information embedded within, or as a layer above, the presentation of information.” In http://www.ics.uci.edu/~fielding/pubs/dissertation/web_arch_domain.htm
33. Hypermedia examples • HTML: <a>, <img>,<video>,<audio> • HTML: <link> – rel = search – rel = stylesheet – rel = next | prev http://www.w3.org/html/wg/drafts/html/master/links.html#linkTypes
34. Hypermedia examples • RFC 5988 – Link relation types: describedby, edit, alternate, … – Registry: • http://www.iana.org/assignments/link-relations/link-relations.xml – HTTP message headers • E.g. https://api.github.com/ • E.g. https://api.github.com/users/pmhsfelix/repos?page=1&per_page=2 • Link: <https://api.github.com/user/364600/repos?page=2&per_page=2>; rel="next", <https://api.github.com/user/364600/repos?page=9&per_page=2>; rel="last"
35. Hypermedia usages • Relation between resources • Embedded external resources • Reference data • Redirection • Access control • Workflow Suggestion: http://vimeo.com/49484938
36. References • Architecture of the World Wide Web, Volume One – http://www.w3.org/TR/webarch/ • HTTP Bis – http://datatracker.ietf.org/wg/httpbis/ • Internet Assigned Numbers Authority – http://www.iana.org/assignments/media-types – http://www.iana.org/assignments/link-relations/link-relations.xml • Subbu Allamaraju, “RESTful Web Services Cookbook” – http://shop.oreilly.com/product/9780596801694.do • Mike Amundsen, “Building Hypermedia APIs with HTML5 and Node” – http://shop.oreilly.com/product/0636920020530.do
37. References http://chimera.labs.oreilly.com/books/1234000001708/index.html
38. Patrocinador “GOLD” Twitter: @PTMicrosoft http://www.microsoft.com/portugal
39. Patrocinadores “Silver”
40. Patrocinadores “Bronze”
41. Próximas reuniões presenciais 21/09/2013 – Setembro (Lisboa) 19/10/2013 – Outubro (Lisboa) 23/11/2013 – Novembro (Lisboa) 14/12/2013 – Dezembro (Lisboa) Reserva estes dias na agenda! :)
42. Obrigado! Pedro Félix mailto:pmhsfelix@gmail.com https://pfelix.wordpress.com https://twitter.com/pmhsfelix