developer and consultant • Telecommunication and media industries • Focus on Web APIs, Identity and Access Management • Co-author of Designing Evolvable Web APIs with ASP.NET, O’Reilly, 2014 – freely available at http://chimera.labs.oreilly.com/books/1234000001708 2
Web (WWW, or simply Web) is an information space in which the items of interest, referred to as resources” In http://www.w3.org/TR/2004/REC-webarch-20041215/ (bolds are mine) 4
Web (WWW, or simply Web) is an information space in which the items of interest, referred to as resources” In http://www.w3.org/TR/2004/REC-webarch-20041215/ (bolds are mine) 5 • Anything identifiable is a resource • Resources aren’t database entities • Collections • Operations • Sensors and actuators • Example: Asynchronous task execution and monitoring • Task creation resource • Task status resource • Task result resource • See section 1.10 in Subbu Allamaraju, “RESTful Web Services Cookbook”
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).” In http://www.w3.org/TR/2004/REC-webarch-20041215/ (bolds are mine) Uniform Resource Identifier Identification 6
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).” In http://www.w3.org/TR/2004/REC-webarch-20041215/ (bolds are mine) Uniform Resource Identifier Identification 7 • Uniformly use URIs to identify the API exposed resources • No need to expose implementation dependent identifiers such as DB ids • No “GetInvoiceById” or “GetCustomerById” • Just “GetAnythingById”, i.e., the HTTP GET method • URIs should be opaque to the clients • Provide URIs via hypermedia • When clients need to build URIs, provide URI templates • https://tools.ietf.org/html/rfc6570 (e.g. http://example.com/search{?q,lang}) • “Cool” URIs helps the development experience • https://www.example.com/invoices/123
Interaction 9 • Provides an uniform interface, independent of the resource type • Uniform resource identification via URIs • Uniform set of methods: GET, POST, PUT, DELETE, PATCH, OPTIONS … • Not only for CRUD • Namely because resources can be operations and not “just” data • Uniform interface enables • Layered system style • Intermediaries • Caching, access control • API Gateways
Interaction 11 • HTTP is an application level protocol • Make good use of it • Status codes, headers, caching, concurrency, fault tolerance • Don’t use it just for transport purposes • Examples • Use standard status code to represent processing results • Use standard caching headers to represent timeliness and cacheability • Use the Authorization header to convey authentication and authorization
Interaction 12 • API for mobile devices • Mainly for media content consumption • Based on a backend with • High latency • Low availability • Solution • Caching • Synchronous revalidation was a problem • Fault tolerance was a problem
Interaction 13 • API for mobile devices • Mainly for media content consumption • Based on a backend with • High latency • Low availability • Solution • Caching • Synchronous revalidation was a problem • Fault tolerance was a problem • Solution 2 – RFC 5861 – “HTTP Cache-Control Extensions for Stale Content” • Stale-while-revalidate • Stale-if-error • Warning header for stale content
resource state links related resources 18 “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
a representation into multiple parts • Relation between resources • E.g. Where is next page on the collection? • E.g. Where are the comments for the current issue • Workflow • E.g. How can I search this collection? • E.g. How to add an element to the collection? • Access control (hinting, not enforcement) • E.g. Can I edit the represented resource? Suggestion: http://vimeo.com/49484938 19 • Beware of the hidden contract • Hypermedia makes application flow possibilities explicit • Hypermedia enables evolvability
Target URI • Link relation • Other attributes • Ways to add links at the HTTP metadata level • Set of link relations • E.g. edit, author, next, previous, alternate, describedby 21 Context Target Relation Other attributes
contain native hyper- linking semantics that induce application flow. For example, HTML is a hypermedia type; XML is not.“ Mike Amundsen (2010) (bolds are mine) • Hypermedia Application Language (HAL) • JSON:API • Siren • Collection+JSON • JSON-LD 23
representations • Representation-first design • State information model • Links control types • Link relations • Beware of the “JSON blank canvas” effect • Use general purpose hypermedia enabled types • Use purpose specific media-types where applicable • application/pdf • application/calendar+json • application/problem+json • application/json-home 24
of HTTP as an application level protocol • Emphasis on representation design • Not an after-thought • Focus of the documentation effort • Take advantage of new media types • Hypermedia types • Purpose specific types • Hypermedia is a key factor for evolvability • However, be prepared to pay the additional cost 29
pmhsfelix
77web
yosuke_furukawa
fsubal
konifar
nearme_tech
kangnux
philipschwarz
kentaroutakeda
genkiogasawara
joergneumann
bkuhlmann
jlugia
bluesmoon
zenorocha
searls
shpigford
sugarenia
addyosmani
mojombo
afnizarnur
maltzj
scottboms
erikaheidi
![Designing Evolvable APIs for the Web Pedro Félix @pmhsfelix [email protected]](https://files.speakerdeck.com/presentations/46ed3cbb9c994d47b37e5af7bce02199/slide_0.jpg){kind=link}
