REST Lecture Notes PDF

Web Engineering (WBCS008-05) Set 3: REST Vasilios Andrikopoulos [email protected] Outline REST Definition Principles Maturity levels API design API specification |2 Definition...

Web Engineering (WBCS008-05) Set 3: REST Vasilios Andrikopoulos [email protected] Outline REST Definition Principles Maturity levels API design API specification |2 Definition |3 REpresentational State Transfer (REST) › REST (as a term) introduced in Roy Fielding’s PhD thesis (2000) › An architectural style for building large- scale distributed hypermedia systems Defines set of constraints Web as an instance of this style |4 Architectural Style vs Architecture Amsterdam Town Hall in the Dutch The Rietveld Schröder House in the Baroque Style Modernist Style (as influenced by the De Stijl movement) |5 Points to keep in mind in the following 1. REST (as a style) cannot be implemented, only adhered to 2. It was defined/distilled from the Web a posteriori 1. Aggregates standards and best practices 2. The Web follows REST principles 3. It is possible to design other RESTful systems that are not the Web, i.e. they do not use URIs and HTTP |6 Goals of the REST style › Scalability System can cope with increasing amount of users › Simplicity Easy to use for any kind of users › Data independence Data of a single resource may be in different formats Users may choose the desired representation › Performance Speed |7 REST in a nutshell › A set of constraints on system architecture: 1. Resource Identification e.g. through URIs 2. Uniform Interface e.g. through HTTP verbs 3. Self-describing Messages: decouple resource from representations 4. Hypermedia as the Engine of Application State (HATEOAS): links between resources 5. Stateless Interactions: separation of resource state from client state › Claimed benefits: scalability, remixability, usability, accessibility, … |8 Resource Identification (RI) › RI: Name everything (resource) that you want to talk about Conversely: anything that can be named can be a resource › For example, in the Web the use of URIs provides a global addressing space for resource and service discovery › Application state also represented as a resource [SI] Links to next pages for multi-page process Paged results identifying follow-up pages |9 RI in practice | 10 Uniform Interface (UI) › UI: The same (small) set of operations applies to all resources [RI] › Small set of verbs applied to large set of nouns Verbs are universal and not application-specific Set of verbs can be extended if there is sufficient demand › Identify operations that can be optimized Safe vs idempotent operations › Build functionality based on useful properties of these operations | 11 Uniform Interface example Client Server GET /accounts HTTP/1.1 Retrieve a list of all current 200 OK accounts GET /accounts/31415 HTTP/1.1 Retrieve a particular account 200 OK POST /accounts HTTP/1.1 Create a new account. Retrieve new account URI 201 Created Content-Location: /accounts/1113 from HTTP Headers PUT /accounts/31415 HTTP/1.1 CREATE Update an account RETRIEVE 204 No content UPDATE DELETE /accounts/31415 HTTP/1.1 DELETE Delete an account 204 No content | 12 Self-Describing Messages (SDM) › Resources are abstract entities → they cannot be used as they are, only identified [RI] and accessed [UI] › SDM: Resources accessed using only resource representations Sufficient to represent a resource Made clear which representation is used for communication Representation format is negotiable › Resource representation can be based on different constraints Same model, different format for different users Representation must support links [HATEOAS] | 13 XML Representations › Extensible Markup Language This is XML (XML) Markup ≡ Annotation What is XML? XML stands for Meta-language eXtensible Markup Language Only syntax, very little semantics Simplification of SGML › Points of distinction: Document type Don’t forget the presentation Portability › Tree-model based | 14 JSON representations { › JavaScript deals with XML by “sentence” : “This is JSON” } parsing it first into a { (Document Object Model) “article” : { “title” : “What is JSON?”, DOM tree “text” : “JSON stands for JavaScript Object Notation” } Inconvenient and ineffective } › JavaScript Object Notation { “note” : { (JSON) encodes data as JS “date” : “22/11/2020”, “from” : { objects “name” : “me”}, “to” : { “name” : “me”}, More efficient if client is in JS “description” : “Don’t forget the presentation” } } | 15 Other representation formats examples XHTML (HTML that can be parsed using an XML parser) Media-type: application/xhtml+xml Atom (XML vocabulary for describing time-stamped entries – used extensively in news feeds) Media-type: application/atom+xml SVG (Scalable Vector Graphics: XML vocabulary for storing and manipulating graphics) Media-type: image/svg+xml RDF (Resource Description Framework: a URI-based knowledge representation framework) through an XHTML Microformat like RDFa Specialized XML vocabularies like MathML or OpenDocument Media-type: application/xml | 16 Hypermedia as the Engine of Application State (HATEOAS) › Resource representations [SDM] contain links to identifiable resources [RI] › HATEOAS: Resources and their state accessed through link navigation › RESTful applications do not call but navigate Traversal paths contained as links in the resources representations [SDM] Navigation to next resource depends on link semantics | 17 Stateless Interactions (SI) › SI: State is moved to clients or resources themselves Avoids state on server-side applications › Resource state managed by the server: the same for all clients, can be changed by a client › Client state managed by the client: maintained by each client separately, affects access to server resources but not the resources themselves › Stateless interaction ≠ stateless application › Security as a major concern due to lack of trust of client state | 18 State Management on the Web › Essential for supporting [HATEOAS] and [SI] › State embedded in every resource representation/URI › Cookies as a very popular alternative Session state (e.g. logged in/out) as a set of variables maintained on client and server side More convenient than state embedding Web frameworks can handle either transparently through URI rewriting | 19 Cookies side-effects › Client-side: Stored persistently independent of resource representation (!) Effectively “shared state” within the context of the same client application, e.g. browser › Server-side (through Session IDs) Require expensive tracking Potentially global/cross-resource Load balancing to be cookie-aware Resource-based state as a useful alternative solution | 20 Resource-based state by example Client Server Show me list of products Here is a list of all products I want to buy 1 of /product/X, I am U:P Added 1 of /product/X to /users/U/basket I want to buy 1 of /product/Y, I am U:P Added 1 of /product/Y to /users/U/basket I do not want /product/X, remove, I am U:P Removed /product/X to /users/U/basket I am done, I am U:P Here is the total cost of items in /users/U/basket | 21 Achieving the REST Goals › Performance [RI+UI] Caching is enabled → “the closer the cache, the faster the response” › Scalability Caching allows serving requests without accessing origin server [HATEOAS+SI] All required state is contained in request No server affinity to requests Requests can be sprayed across clustered servers (load balancing) | 22 Achieving the REST Goals (cont.) › Simplicity [UI] Standardized interface to all resources allows of simpler interaction design › Data independence [SDM] Different formats are available for each resource Content can be tailored to client’s capabilities | 23 Maturity Model | 24 Maturity Levels of REST Applications › Introduced by Richardson in 2008 › Helps explain properties of applications › Used as a metric for compliance to REST principles 1. Resource Identification Level 3: Hypermedia 2. Uniform Interface Controls (4) + (5) 3. Self-describing Messages Level 2: HTTP Verbs (2) + (3) 4. Hypermedia as the Engine of Application State Level 1: Resources (1) 5. Stateless Interactions Level 0: POX (Plain old XML) | 25 Level 0 › Simply using HTTP as a transport system for remote interactions Without using any of the mechanisms of the Web Essentially using HTTP as a tunneling mechanism for RPC Any representation of resources possible Resources are identifiable Data and meta-data in the message body | 26 Level 1 › Resources are uniquely identifiable by URIs Example resources: doctor, appointment slot Interactions target these resources Data and meta-data in the message body | 27 Level 2 › Uses HTTP Verbs correctly to interact with resources All verbs and all standard responses (response codes – even for faults) Meta-data used to identify the resource in URI | 28 Level 3 › Introduces HATEOAS & SI – hypermedia controls Provides the representation to the next valid state change operations on the resource (link) Provides the URI of the resource Allows for dynamic changes in the URIs, extend the set of links to a resource Warning: no universal standard for representing hypermedia controls Here ATOM: e.g. | 29 Level 3 example GET /doctors/mjones/slots?date=20100104&status=open HTTP/1.1 Host: royalhope.nhs.uk HTTP/1.1 200 OK [various headers] | 30 Level 3 example (cont.) POST /slots/1234 HTTP/1.1 [various other headers] HTTP/1.1 201 Created Location: http://royalhope.nhs.uk/slots/1234/appointment [various headers] … | 31 API Design | 32 SWEBOK’s definition An application programming interface (API) is the set of signatures that are exported and available to the users of a library or a framework to write their applications. Besides signatures, an API should always include statements about the program’s effects and/or behaviors (i.e., its semantics). | 33 | 34 | 35 | 36 | 37 | 38 | 39 RESTful APIs Design Principles Information abstraction of a key element constitutes a resource Resource representation is a sequence of bytes, plus representation metadata; the representation is negotiable All interactions are context-free i.e. state agnostic Components can perform only a small set of well-defined methods Idempotency of operations and representation metadata is encouraged Presence of intermediaries is promoted | 40 Note on rule formulation › Requirement verbs in the following are compliant with RFC 2119 definitions, namely: 1. MUST/REQUIRED/SHALL: absolute requirement 2. MUST/SHALL NOT : absolute prohibition 3. SHOULD/RECOMMENDED: there may be valid reasons to ignore this item, but full implications must be taken into consideration 4. SHOULD NOT/NOT RECOMMENDED: (as above, but for accepting a particular behavior) 5. MAY/OPTIONAL: truly optional | 41 Interface › URI format / operator must be used to indicate a hierarchical relationship (no trailing /es) Design for readability (use -, avoid _, prefer lower case letters) since they may be used in browsers File extensions should not be included in URIs to emphasize content negotiation › URI Authority Consistent subdomain names should be used for APIs & client developer portal (if any) | 42 Interface: Path Design › Singular noun should be used for document names i.e. single resources, e.g. http://api.soccer.restapi.org/leagues/seattle › Plural nouns should be used for collections or stores (client-managed resource repositories) e.g. http://api.music.restapi.org/artists/ mikemassedotcom/playlists › Verbs or verb phrases for controllers (executable functions) e.g. POST /alerts/245743/resend › CRUD function names should not be used | 43 Interface: Query Design › Query component may be used to filter collections or stores e.g. GET /users?role=admin › Query component may be used for pagination or subsetting e.g. GET /users?pageSize=25&pageStartIndex=50 | 44 Interactions › Request methods GET and POST must not be used to tunnel other request methods GET must be used to retrieve a representation of a resource (only) PUT must be used for both insert (in a store) and update PUT must be used to update (any) mutable resources | 45 Interactions (cont.) › Request methods (cont.) POST must be used to create a new resource in a collection e.g. POST /leagues/seattle/teams/trebuchet/players POST must be used to execute controllers e.g. POST /alerts/245743/resend DELETE must be used to remove a resource from its parent › Response Status Codes semantics must be strictly enforced | 46 Metadata: HTTP Headers › Content-Type must be used › Content-Length should be used › Last-Modified should be used in responses › Stores must support conditional PUT requests › Location header must be used to specify the URI of a new resource › Cache-Control, Expires, and Date response headers should be used (caching) › Custom HTTP headers must not be used to change the behavior of HTTP methods | 47 Metadata: Media types › Application-specific media types should be used e.g. not simply “application/json” But it is preferable to “text/plain” › Media type negotiations should be supported › Media type selection by query parameter may be supported e.g. GET /bookmarks/mikemassedotcom?accept=application/xml | 48 Representation: Message Body Format › JSON should be supported for resource representation by default › JSON must be well-formed (mixed lower case without special characters when possible) › XML and other formats may optionally be used › Additional envelopes must not be created (i.e. body contains the resource state representation only) | 49 Representation: Hypermedia › Hypermedia Representation A consistent form should be used for link representation, link relation representation, and link advertisement A self link should be included in response message body representations Minimize the number of advertised entry point URLs Links should be used to advertise a resource’s available actions in a state- sensitive manner › Media Type Representation A consistent form should be used to represent media type formats and schemas | 50 Representation: Errors › A consistent form should be used to represent errors and error responses › Consistent error types should be used for common error conditions | 51 Client concerns › Versioning New URIs should be used to introduce new concepts Schemas should be used to manage representational form versions › Security Oauth (Open Authorization) may be used to protect resources API Management solutions may be used to protect resources › Response Representation Composition URI query component should be used to support partial responses or to embed linked resources | 52 Read-only resource design 1. One-off resources like top-level directories Define data model 2. A resource for each exposed object 3. Resources representing Split data into resources the results of algorithms Name resources with URIs Design representations Link between resources Model typical sequence of events Define error conditions | 53 Read/Write resource design Define data model (+users) Split data into resources Name resources with URIs Define supported uniform interface subset Design representations (accepted) Design representations (served) Link between resources Model typical sequence of events Define error conditions | 54 Other guidelines for RESTful API design › Guidelines available by multiple sources such as Google applicable also to non-REST APIs Microsoft with plenty of examples Zalando (!) leaning heavily on OpenAPI (see next slides) › Take a look at the “live” collection maintained by Erik Wilde for more › The ProgrammableWeb offers a wide list of APIs for inspiration | 55 API Specification | 56 API Specification › Defines in an ideally both machine- and human-readable format: What the API offers How to interact with it (in terms of payload) › Code generation a common desirable feature › Documentation generation the main goal › OpenAPI as the evolution of Swagger | 57 OpenAPI › Programming-language agnostic interface description language for (RESTful) APIs Current version 3.0.2 (2018) Take a look at the OpenAPI3 map › Specifications a OpenAPI Specification-compliant documents In JSON or YAML (Yet Another Markup Language YAML Ain’t Markup Language) format Fixed (name) or (regex) Patterned fields Builds on JSON Schema (!) for data type definitions Single document, or spread across multiple documents with JSON Schema $ref fields pointing to each other | 58 Samples { "title": "Sample Pet Store App", "description": "This is a sample server for a pet store.", "termsOfService": "http://example.com/terms/", "contact": { "name": "API Support", "url": "http://www.example.com/support", "email": "[email protected]" }, "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "version": "1.0.1“ } | 59 Samples { "/pets": { "get": { "description": "Returns all pets from the system that the user has access to", "responses": { "200": { "description": "A list of pets.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/pet" } } } } } } } } } | 60 Other specification efforts › Other standards Web Services Description Language (WSDL) 2.0 (how-to) › Non-standards json:api Web Resource Modeling Language (WRML) RESTful API Modeling Language (RAML) API Blueprint › Note: documentation ⊂ specification Almost all back-end frameworks come with documentation generation features Examples of good API documentation | 61 Self-evaluation questions › Which constraints define the REST architectural style, and how are they related with each other? › How are the REST style constraints related to its goals? › What are the maturity levels in Richardson's model? Which REST principles are they related to? › What are the principles that should govern the design of RESTful APIs? › What steps should be followed for the design of a RESTful API according to Masse's book? | 62 Source material Erik Wilde’s lecture on REST http://dret.net/lectures/web- fall10/rest Masse, Mark. REST API design rulebook: designing consistent RESTful web service interfaces. " O'Reilly Media, Inc.", 2011. | 63 Next lecture Architectural concerns | 64