Demystifying the REST API

824 views

Published on

Are you confused by REST APIs? Can't tell a PUT from a POST? No idea what a non-idempotent operation is? Despite their ubiquity, the details of what makes an API RESTful are often lost even on experienced developers. We'll cover the basics of the HTTP protocol that drives most REST services, break down the lingo, and clear up some misconceptions about this powerful and popular methodology.

Published in: Technology
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
824
On SlideShare
0
From Embeds
0
Number of Embeds
23
Actions
Shares
0
Downloads
27
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide

Demystifying the REST API

  1. 1. Demystifying the REST API Samantha Quiñones (@ieatkillerbees)
  2. 2. @ieatkillerbees http://samanthaquinones.com
  3. 3. Engineer A person who designs, builds, or maintains things.
  4. 4. Pattern A model or design used to guide the building of things.
  5. 5. REST (Representational State Transfer) An architectural pattern for distributed hypermedia systems.
  6. 6. REST[ful] API A resource-oriented API built to conform with the REST architectural pattern.
  7. 7. Hypermedia A non-linear medium of many disparate types of information, including text, images, video, audio and hypertext.
  8. 8. I’m not here to tell you… How to Build an API
  9. 9. -Roy Fielding, REST Discussion Mailing List “[T]he goal of my dissertation is to teach people how to think about the problem in terms of trade-offs, not in terms of rigid repetition…”
  10. 10. Nothing is more easy than to reduce this mass to one quarter of its bulk. You know that curious cellular matter which constitutes the elementary tissues of vegetable? This substance is found quite pure in many bodies, especially in cotton, which is nothing more than the down of the seeds of the cotton plant. Now cotton, combined with cold nitric acid, become transformed into a substance eminently insoluble, combustible, and explosive. It was first discovered in 1832, by Braconnot, a French chemist, who called it xyloidine. In 1838 another Frenchman, Pelouze, investigated its different properties, and finally, in 1846, Schonbein, professor of chemistry at Bale, proposed its employment for purposes of war. This powder, now called pyroxyle, or fulminating cotton, is prepared with great facility by simply plunging cotton for fifteen minutes in nitric acid, then washing it in water, then drying it, and it is ready for use.
  11. 11. Nothing is more easy than to reduce this mass to one quarter of its bulk. You know that curious cellular matter which constitutes the elementary tissues of vegetable? This substance is found quite pure in many bodies, especially in cotton, which is nothing more than the down of the seeds of the cotton plant. Now cotton, combined with cold nitric acid, become transformed into a substance eminently insoluble, combustible, and explosive. It was first discovered in 1832, by Braconnot, a French chemist, who called it xyloidine. In 1838 another Frenchman, Pelouze, investigated its different properties, and finally, in 1846, Schonbein, professor of chemistry at Bale, proposed its employment for purposes of war. This powder, now called pyroxyle, or fulminating cotton, is prepared with great facility by simply plunging cotton for fifteen minutes in nitric acid, then washing it in water, then drying it, and it is ready for use.
  12. 12. NASA/JPL-Caltech
  13. 13. The REST Architectural Style
  14. 14. © Henry Story, 2007 (CC BY-NC 2.0)
  15. 15. Architectural Styles and the Design of Network-based Software Architectures Roy T. Fielding (http://www.ics.uci.edu/~fielding/pubs/dissertation/faq.htm)
  16. 16. MySQL PHP 5.6 NGINX Symfony 2 RabbitMQ
  17. 17. WWW Null Style
  18. 18. Client-Server Architecture ServerClient
  19. 19. Statelessness ServerClient Client Client
  20. 20. Cache ServerClient Client Client
  21. 21. Uniform Interface Server Client Client Client Server R R S H R R S H
  22. 22. Layered System Server Client Client Client Server R R S H R R S H Gateway Proxy
  23. 23. Code On Demand Server Client Client Client Server R R S H R R S H Gateway Proxy
  24. 24. The Uniform Interface
  25. 25. Resource A thing, or a collection of things that… May be concrete, or abstract… May be static, or vary over time… Has a name that is unique… Uniform Interface
  26. 26. Uniform Interface
  27. 27. Resource Identifier A unique name which is… A conceptual mapping to a resource… Or a collection of resources… Uniform Interface
  28. 28. http://galaxies.tembies.com/groups/local/galaxies/ngc4258.json “The most recent 10 tweets containing the hashtag ‘#MWPHP’” Uniform Interface
  29. 29. Representation A sequence of bytes that… Contains the state of a resource… Consists of data… Metadata about the data… Metadata about the metadata… Uniform Interface
  30. 30. { "name": "Messier 106", "ngc_id": 4258, "type": "SAB(s)bc", "size": 135000 } Uniform Interface
  31. 31. Content-Type: application/json { "name": "Messier 106", "ngc_id": 4258, "type": "SAB(s)bc", "size": 135000 } Uniform Interface
  32. 32. Content-Type: application/json Cache-Control: max-age=3600 public { "name": "Messier 106", "ngc_id": 4258, "type": "SAB(s)bc", "size": 135000 } Uniform Interface
  33. 33. Self-Contained Messages Contains all information necessary to… Process the request… Return an appropriate representation… Uniform Interface
  34. 34. Hypermedia As The Engine Of Application State
  35. 35. <galaxy> <ngc_id>4258</ngc_id> <name/>Messier 106</name> <type>SAB(s)bc</type> <size>135000</size> <link rel="group" href="/groups/local" /> <link rel="self" href="/groups/local/galaxies/ngc4258" /> </galaxy>
  36. 36. Hypermedia Formats HTML XML CSS Atom
  37. 37. JSON is not a Hypermedia Format
  38. 38. JSON Hypermedia Collection +JSON JSON-LD JSON:API UBER JSON+HAL
  39. 39. Hypertext Application Language A proposed (2012) standard that… Expresses relationships between resources… Supports JSON (JSON+HAL)… Supports XML (XML+HAL)…
  40. 40. { "name": "Messier 106", "ngc_id": 4258, "type": "SAB(s)bc", "size": 135000, "_links": { "self": { "href": "/groups/local/galaxies/ngc4258" } }, "group": { "href": "/groups/local" } } } }
  41. 41. HTTP (Hyper Text Transport Protocol)
  42. 42. Version 0.9 (1991) Version 1.0 (1996) Version 1.1 (1999)
  43. 43. GET POST OPTIONS HEAD DELETE TRACE PUT PATCH CONNECT
  44. 44. Idempotent UnsafeSafe GET POST OPTIONS HEAD DELETE TRACE PUT PATCH CONNECT
  45. 45. Idempotence A property of an operation that can be applied multiple time without changing the result, such that ƒ(ƒ(𝑥)) = ƒ(𝑥)
  46. 46. GET Request the representation of a resource with a given identifier SafeIdempotent
  47. 47. GET /groups/local/galaxies/ncg4258 HTTP/1.1 Host: galaxies.tembies.com Content-Type: application/json; charset=UTF-8
  48. 48. HTTP/1.1 200 OK Content-Length: 207 Content-Type: application/json; charset=UTF-8 { "name": "Messier 106", "ngc_id": 4258, "type": "SAB(s)bc", "size": 135000, "_links": { "self": { "href": "/groups/local/galaxies/ngc4258" } }, "group": { "href": "/groups/local" } } } }
  49. 49. HEAD Request the representation metadata and control data for a resource with a given identifier SafeIdempotent
  50. 50. GET /groups/local/galaxies/ncg4258 HTTP/1.1 Host: galaxies.tembies.com Content-Type: application/json; charset=UTF-8
  51. 51. HTTP/1.1 200 OK Content-Length: 207 Content-Type: application/json; charset=UTF-8
  52. 52. TRACE Request the server respond by echoing the request. SafeIdempotent
  53. 53. TRACE /groups/local/galaxies/ncg4258 HTTP/1.1 Host: galaxies.tembies.com Content-Type: application/json; charset=UTF-8
  54. 54. HTTP/1.1 200 OK Content-Type: message/http Content-Length: 39 TRACE /groups/local/galaxies/ncg4258 HTTP/1.1 Host: galaxies.tembies.com Content-Type: application/json; charset=UTF-8
  55. 55. OPTIONS Request the server respond with information about what methods are allowed for a resource. SafeIdempotent
  56. 56. OPTIONS /groups/local/galaxies/ncg4258 HTTP/1.1 Host: galaxies.tembies.com Content-Type: application/json; charset=UTF-8
  57. 57. HTTP/1.1 200 OK Content-Type: message/http Content-Length: 39 Allow: GET,HEAD,DELETE,POST,OPTIONS,TRACE
  58. 58. DELETE Request the server delete the resource. UnsafeIdempotent
  59. 59. DELETE /groups/local/galaxies/ncg4258 HTTP/1.1 Host: galaxies.tembies.com Content-Type: application/json; charset=UTF-8
  60. 60. HTTP/1.1 204 No Content
  61. 61. PUT Request the server store a provided representation of a resource at the specified name, replacing the existing resource if it exists. UnsafeIdempotent
  62. 62. PUT /groups/local/galaxies/ncg4258 HTTP/1.1 Host: galaxies.tembies.com Content-Type: application/json; charset=UTF-8 { "name": "Messier 106", "ngc_id": 4258, "type": "SAB(s)bc", "size": 135000, “example_type": "contrived", "_links": { "self": { "href": "/groups/local/galaxies/ngc4258" } }, "group": { "href": "/groups/local" } } } }
  63. 63. HTTP/1.1 204 No Content
  64. 64. POST Request the server store a provided representation of a resource as a new member of the collection identified by the resource name UnsafeNot Idempotent
  65. 65. POST /groups/local/galaxies HTTP/1.1 Host: galaxies.tembies.com Content-Type: application/json; charset=UTF-8 { "name": "Messier 51a", "ngc_id": 5194, "type": “SA(s)bc pec", "size": 60000, }
  66. 66. HTTP/1.1 201 Created Location: /groups/local/galaxies/ngc4258 { "_links": { "self": { "href": "/groups/local/galaxies/ngc4258" } } } }
  67. 67. PUT vs POST or How Yelling Loudly Can Make a Difference
  68. 68. PUT Create or replace… a Resource or collection Can be repeated… safely POST Append to a collection Can not be repeated… safely
  69. 69. Idempotency ServerClient PUTPUTPUT
  70. 70. Idempotency ServerClient POSTPOSTPOST
  71. 71. Antipattern A common solution to an engineering problem that is, at best ineffective, and at worst, potentially destructive.
  72. 72. Overloading GET (or POST) GET /things/42?action=delete GET /widgets/42/delete GET /widgets/delete?id=42 Antipattern
  73. 73. Abusing Status Codes HTTP/1.1 200 OK { "success": false, "code": "ID10T", "message": "Tweet @jakeasmith for lols" } Antipattern
  74. 74. Abusing Status Codes Antipattern 1xx - Informational 2xx - Success 3xx - Redirection 4xx - Client Error 5xx - Server Error
  75. 75. Relying on Session REST APIs are Stateless Antipattern
  76. 76. Not Supporting Caching Learn to use cache headers Antipattern
  77. 77. Your Humble Speaker’s Loud and Oft-Repeated Advice
  78. 78. Sanitize Assumptions Patterns like REST make assumptions safer. The further you are from the consumers of your API, the closer you should adhere to the pattern. Advice
  79. 79. Avoid Side-Effects GET is a safe method. GET should never, never, cause side effects. Advice
  80. 80. Document your APIs REST APIs are self-documenting. That’s a feature, not an excuse. Advice
  81. 81. Understand When REST Works Resource (noun) oriented CRUD Open consumption Open formats Advice
  82. 82. And When It Doesn’t Action (verb) oriented RPC Closed consumption Closed formats Advice
  83. 83. After the Conference
  84. 84. Give Me Some Feedback! https://joind.in/13067
  85. 85. Read the Dissertation http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm
  86. 86. Read the RFC https://www.ietf.org/rfc/rfc2616.txt
  87. 87. Learn about Caching http://www.mobify.com/blog/beginners-guide-to-http-cache-headers/
  88. 88. Check Out Some Documentation Frameworks RAML - http://raml.org API Blueprint - http://apiblueprint.org Swagger - http://swagger.io
  89. 89. Consider Some Further Reading Build APIs You Won't Hate by Phil Sturgeon RESTful Web Services by Leonard Richardson & Sam Ruby
  90. 90. Build an Awesome API Easy to maintain Meets your needs Solves a problem
  91. 91. Tell Your Community how you built it at a user group or a conference
  92. 92. Other Resources • RFC 2616 “Hypertext Transfer Protocol” (http://bit.ly/LkW6OW) • RFC 5789 “PATCH Method for HTTP” (http://bit.ly/1cFpvtq) • JSON HAL Proposal (http://bit.ly/1kJLvgw) • RFC 6902 “JSON PATCH” (http://bit.ly/LkWyww) • Fielding’s Dissertation (http://bit.ly/1eTY8AI) • REST Cookbook (http://restcookbook.com) • HATEOAS for PHP: http://hateoas-php.org/ • Well-supported, Symfony-ready HATEOAS library • REST APIs with Symfony2: The Right Way (http://williamdurand.fr/2012/08/02/rest-apis-with-symfony2-the-right-way/)

×