Design and implementation of Web APIs Pedro Félix http://netponto.org 41ª Reunião Presencial - 21/09/2013 

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 

Agenda • Web APIs • The architecture of the Web • The HTTP protocol • Internet Media Types • Hypermedia 

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 

Web APIs Source: http://blog.programmableweb.com/2012/02/06/5000-apis-facebook-google-and-twitter-are-changing-the-web/ 

Web APIs Source:http://blog.programmableweb.com/2012/11/26/8000-apis-rise-of-the-enterprise/ 

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/ 

Example: Google API Console 

API Types Server Client 

API Types Server Client 

API Types Server Client 

API Types Server Client Client Client 

API Types Server Client Client Client Server Server 

Web APIs • Application Programming Interfaces • Exposed on the Web • Using HTTP as the application protocol • Accessible by multiple client types – E.g. Mobile devices 

The Architecture of the Web 

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/ 

The Architecture of the Web Resource User-Agent Representation Uniform Resource Identifier Format 

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 

Web API design • Use HTTP as an application protocol – Method semantics – Content-negotiation – Caching – Concurrency – Fault tolerance – Security 

HTTP Messages Method Target Request Metadata Metadata Representation Resource Status Code Response Metadata Metadata Representation Request Message Response Message 

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 

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 

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 

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 – ... 

200 OK GET Example: asynchronous job /jobs/1 POST 202 Accepted /instances/123 GET /results/456 303 See Other GET 200 OK 200 OK 

Representations and media types • application/octet-stream • text/plain • text/csv • application/xml, application/json • text/html • text/calendar • image/gif 

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 

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 

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 

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 

Conditional Requests • Two goals – More efficient cache revalidation – Optimistic concurrency control • Validators – Last-Modified – Etag (entity-tag – opaque identifier) 

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 

Hypermedia examples • HTML: , ,, • HTML: – rel = search – rel = stylesheet – rel = next | prev http://www.w3.org/html/wg/drafts/html/master/links.html#linkTypes 

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: ; rel="next", ; rel="last" 

Hypermedia usages • Relation between resources • Embedded external resources • Reference data • Redirection • Access control • Workflow Suggestion: http://vimeo.com/49484938 

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 

References http://chimera.labs.oreilly.com/books/1234000001708/index.html 

Patrocinador “GOLD” Twitter: @PTMicrosoft http://www.microsoft.com/portugal 

Patrocinadores “Silver” 

Patrocinadores “Bronze” 

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! :) 

Obrigado! Pedro Félix mailto:[email protected] https://pfelix.wordpress.com https://twitter.com/pmhsfelix