Share
Embed
Design and implementation of Web APIs
Session presented at the 41th meeting of the NetPonto community, September 2013
Pedro Felix
September 21, 2013
Transcript
42 slides
-
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 -
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/ -
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 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 • 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: <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 -
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" -
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 -
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! :)