Rest Essentials
Download as PPTX, PDF1 like475 views
This document discusses REST (Representational State Transfer) and best practices for designing RESTful APIs. It covers the history and principles of REST, including the Richardson Maturity Model and REST constraints like client-server architecture, uniform interfaces, layered systems, caching, statelessness and code-on-demand. It also provides guidelines for URI design, resource modeling, HTTP methods, response caching, content negotiation, authentication and enabling cross-origin access.
Rest Essentials
- 3. WorldWideWeb Project Tim Berners-Lee, CERN, 1990 • URI syntax • HTTP • HTML • Web server • Web browser (“Nexus”) • HTML editor (“WYSIWYG”)
- 4. Representational State Transfer Roy Fielding, Ph.D. dissertation, 2000 REST is not: • Protocol • RPC (e.g. SOAP, WSDL) • HTTP • URIs REST is Web’s architectural style
- 6. Resource state • HTML • JSON • HTML • CSV • …
- 7. REST Constraints 1. Client-server 2. Uniform interface 3. Layered system 4. Cache 5. Stateless 6. Code-on-demand
- 8. Client-server • Implemented independently • Deployed independently • Evolve independently
- 9. Uniform Interface 1. Identification of resources • http://example.org/resources/1234 2. Manipulation of resources through representations • HTML • XML • JSON • … 3. Self-descriptive messages • Accept: text/plain • Content-Type: text/plain 4. Hypermedia as the engine of application state (HATEOAS) • <link rel = "self" uri = "/resources/1234"/> • <link rel = "/linkrels/resource/delete" uri = "/resources/1234/delete"/>
- 10. Layered System Enables intermediaries (proxies, gateways) for: 1. Enforcement of security 2. Response caching 3. Load balancing
- 11. Cache • Reduce latency • Increase availability • Increase reliability • Reduce server load
- 12. Stateless • No server state • No server session • Client must include all of the contextual information
- 13. Code-On-Demand • Java applets • JavaScript • Flash • Silverlight • …
- 14. “/” to indicate a hierarchical relationship http://api.canvas.restapi.org/shapes/polygons/quadrilaterals/squares
- 15. “-” to improve the readability of URIs • http://api.example.org/dummy-resources/dummy-resource “_” should not be used in URIs • http://api.example.org/dummy_resources/dummy_resource
- 16. Lowercase should be preferred in URI paths RFC 3986: URIs are case-sensitive except scheme and host • http://api.example.restapi.org/my-folder/my-doc • HTTP://API.EXAMPLE.RESTAPI.ORG/my-folder/my-doc • http://api.example.restapi.org/My-Folder/my-doc
- 17. File extensions should not be included in URIs • http://api.college.restapi.org/students/123/transcripts/2005/fall.json • http://api.college.restapi.org/students/123/transcripts/2005/fall
- 18. Consistent subdomain names should be used for your APIs • http://api.soccer.restapi.org Consistent subdomain names should be used for your client developer portal • http://developer.soccer.restapi.org
- 19. Resource Archetypes • Document • Collection • Store • Controller
- 20. Document – base archetype Contains fields and links • http://api.soccer.restapi.org/leagues/seattle • http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet • http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/mike • http://api.soccer.restapi.org – docroot
- 21. Collection – directory of resources • http://api.soccer.restapi.org/leagues • http://api.soccer.restapi.org/leagues/seattle/teams • http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players
- 22. Store – client-managed resource repository • PUT /users/1234/favorites/alonso
- 23. Controller – models a procedural concept • POST /alerts/245743/resend
- 24. A singular noun should be used for document names • http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players/claudio A plural noun should be used for collection names • http://api.soccer.restapi.org/leagues/seattle/teams/trebuchet/players
- 25. A verb or verb phrase should be used for controller names • http://api.college.restapi.org/students/morgan/register • http://api.example.restapi.org/lists/4324/dedupe • http://api.ognom.restapi.org/dbs/reindex • http://api.build.restapi.org/qa/nightly/runTestSuite
- 26. CRUD function names should not be used in URIs • DELETE /users/1234 • GET /deleteUser?id=1234 • GET /deleteUser/1234 • DELETE /deleteUser/1234 • POST /users/1234/delete
- 27. The query component of a URI may be used to filter collections or stores • GET /users • GET /users?role=admin
- 28. The query component of a URI should be used to paginate collection or store results • GET /users?pageSize=10&pageStartIndex=50
- 29. GET to retrieve a representation of a resource GET /greeting HTTP/1.1 User-Agent: curl/7.20.1 Host: api.example.restapi.org Accept: */* HTTP/1.1 200 OK Date: Sat, 20 Aug 2011 16:02:40 GMT Server: Apache Expires: Sat, 20 Aug 2011 16:03:40 GMT Cache-Control: max-age=60, must-revalidate ETag: text/html:hello world Content-Length: 130 Last-Modified: Sat, 20 Aug 2011 16:02:17 GMT Vary: Accept-Encoding Content-Type: text/html <html> <head><meta charset="utf-8"><title>Greeting</title></head> <body><div id="greeting">Hello World!</div></body> </html>
- 30. HEAD to retrieve response headers HEAD/greeting HTTP/1.1 User-Agent: curl/7.20.1 Host: api.example.restapi.org Accept: */* HTTP/1.1 200 OK Date: Sat, 20 Aug 2011 16:02:40 GMT Server: Apache Expires: Sat, 20 Aug 2011 16:03:40 GMT Cache-Control: max-age=60, must- revalidate ETag: text/html:hello world Content-Length: 130 Last-Modified: Sat, 20 Aug 2011 16:02:17 GMT Vary: Accept-Encoding Content-Type: text/html
- 31. PUT to insert and update a stored resource • PUT /accounts/4ef2d5d0-cb7e-11e0-9572-0800200c9a66/buckets/objects/4321 POST to create a new resource in a collection • POST /leagues/seattle/teams/trebuchet/players
- 32. POST to execute controllers • POST /alerts/245743/resend DELETE to remove a resource from its parent • DELETE /accounts/4ef2d5d0-cb7e-11e0-9572-0800200c9a66/buckets/objects/4321
- 33. OPTIONS to retrieve a resource’s available interactions • Allow: GET, PUT, DELETE
- 34. Metadata Design • Content-Type • Content-Length • Last-Modified • Etag • Stores must support conditional PUT requests • If-Unmodified-Since • If-Match <ETag> • Location - to specify the URI of a newly created resource
- 35. Metadata Design • Cache-Control, Expires, and Date to encourage caching • Cache-Control: max-age=60, must-revalidate • Date: Tue, 15 Nov 1994 08:12:31 GMT • Expires: Thu, 01 Dec 1994 16:00:00 GMT • Cache-Control, Expires, and Pragma to discourage caching • Cache-Control: no-cache • Pragma: no-cache (HTTP 1.0) • Expires: 0 (HTTP 1.0) • Caching should be encouraged • Use small max-age instead of no-cache
- 36. Custom HTTP headers must not be used Use: • Request body • Response body • URI
- 37. Media Types Syntax: type "/" subtype ( ";" parameter )*
- 38. Media type negotiation should be supported when multiple representations are available • Accept: application/json Media type selection using a query parameter may be supported • GET /bookmarks/podolsks?accept=application/xml
- 39. JSON should be supported for resource representation JSON must be well-formed { "firstName" : "Osvaldo", "lastName" : "Alonso", "firstNamePronunciation" : "ahs-VAHL-doe", "number" : 6, "birthDate" : "1985-11-11" }
- 40. OAuth may be used to protect resources http://oauth.net
- 41. The query component of a URI should be used to support partial responses # Request GET /students/morgan?fields=(firstName,birthDate) HTTP/1.1 Host: api.college.restapi.org # Response HTTP/1.1 200 OK Content-Type: application/wrml; format="http://api.formats.wrml.org/application/json"; schema="http://api.schemas.wrml.org/college/Student"; fields="(birthDate,firstName)" { "firstName" : "Morgan", "birthDate" : "1992-07-31" }
- 42. The query component of a URI should be used to embed linked resources # Request GET /students/morgan?embed=(favoriteClass) HTTP/1.1 Host: api.college.restapi.org # Response HTTP/1.1 200 OK Content-Type: application/wrml; format="http://api.formats.wrml.org/application/json"; schema="http://api.schemas.wrml.org/college/Student"; embed="(favoriteClass)" { "firstName" : "Morgan", "birthDate" : "1992-07-31", "favoriteClass" : { "id" : "japn-301", "name" : "Third-Year Japanese", "links" : { "self" : { "href" : "http://api.college.restapi.org/classes/japn-301", "rel" : "http://api.relations.wrml.org/common/self" } } } ... }
- 43. Same-origin policy origin = scheme + host + port Compared URL Outcome Reason http://www.example.com/dir/page2.html Success Same protocol, host and port http://www.example.com/dir2/other.html Success Same protocol, host and port http://username:password@www.example.com/dir2/other.html Success Same protocol, host and port http://www.example.com:81/dir/other.html Failure Same protocol and host but different port https://www.example.com/dir/other.html Failure Different protocol http://en.example.com/dir/other.html Failure Different host http://example.com/dir/other.html Failure Different host (exact match required) http://v2.www.example.com/dir/other.html Failure Different host (exact match required) http://www.example.com:80/dir/other.html Depends Port explicit. Depends on implementation in browser
- 44. JSONP should be supported to provide multi- origin read access from JavaScript # Request GET /players/1421?callback=showPlayerFullName HTTP/1.1 Host: api.soccer.restapi.org # Response HTTP/1.1 200 OK Content-Type: application/javascript showPlayerFullName( { "firstName" : "Kasey", "lastName" : "Keller", "number" : 18, "birthDate" : "1969-11-29", "links" : { "self" : { "href" : "http://api.soccer.restapi.org/players/1421", "rel" : "http://api.relations.wrml.org/common/self" } } } );
- 45. CORS should be supported to provide multi- origin read/write access from JavaScript CORS = Cross-origin resource sharing Request headers: • Origin • Access-Control-Request-Method • Access-Control-Request-Headers Response headers: • Access-Control-Allow-Origin • Access-Control-Allow-Credentials • Access-Control-Expose-Headers • Access-Control-Max-Age • Access-Control-Allow-Methods • Access-Control-Allow-Headers