Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

A Conversation About REST - Extended Version

1,390 views

Published on

Published in: Business, Technology
  • Be the first to comment

A Conversation About REST - Extended Version

  1. 1. A Conversation About REST Jeremy Brown notmessenger.com
  2. 2. What is an API?
  3. 3. What is an API?From Wikipedia:An application programming interface (API)is a particular set of rules and specificationsthat a software program can follow to accessand make use of the services and resourcesprovided by another software program thatimplements the API.
  4. 4. What is an API?Wikipedia continues:It serves as an interface between differentsoftware programs and facilitates theirinteraction, similar to the way the userinterface facilitates interaction betweenhumans and computers.
  5. 5. What is an API?Our understanding:Set of rules and specifications to facilitatethe interaction between different softwareprograms.
  6. 6. Examplesmkdirformat
  7. 7. Types of APIsXML-RPC (1998)SOAP (1998, 2003)JSON-RPC (2005)REST (2000)
  8. 8. XML-RPCxmlrpc.comIt’s remote procedure calling using HTTP asthe transport and XML as the encoding.XML-RPC is designed to be as simple aspossible, while allowing complex datastructures to be transmitted, processed andreturned.
  9. 9. XML-RPCxmlrpc.com also says:We wanted a clean, extensible format that’s verysimple. It should be possible for an HTML coder tobe able to look at a file containing an XML-RPCcall, understand what it’s doing, and be able tomodify it and have it work on the first or secondtry... We also wanted it to be an easy protocolthat could quickly be adapted to run in otherenvironments or on other operating systems.
  10. 10. XML-RPCSample Request:<?xml version="1.0"?><methodCall> <methodName>getStateName</methodName> <params> <param> <value><int>40</int></value> </param> </params></methodCall>
  11. 11. XML-RPCSample Request:<?xml version="1.0"?><methodCall> <methodName>getStateName</methodName> <params> <param> <value><int>40</int></value> </param> </params></methodCall>Sample Response:<?xml version="1.0"?><methodResponse> <params> <param> <value><string>South Dakota</string></value> </param> </params></methodResponse>
  12. 12. SOAPSOAP spec:SOAP is a lightweight protocol for exchange ofinformation in a decentralized, distributedenvironment. It is an XML based protocol thatconsists of three parts: an envelope that defines aframework for describing what is in a message andhow to process it, a set of encoding rules forexpressing instances of application-defined datatypes,and a convention for representing remote procedurecalls and responses.
  13. 13. SOAPSample Request:POST /InStock HTTP/1.1Host: www.example.orgContent-Type: application/soap+xml; charset=utf-8Content-Length: 299<?xml version="1.0"?><soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"> <soap:Header> </soap:Header> <soap:Body> <m:GetStockPrice xmlns:m="http://www.example.org/stock"> <m:StockName>IBM</m:StockName> </m:GetStockPrice> </soap:Body></soap:Envelope>
  14. 14. JSON-RPCWikipedia says:JSON-RPC is a remote procedure callprotocol encoded in JSON. It is a very simpleprotocol (and very similar to XML-RPC),defining only a handful of data types andcommands.
  15. 15. JSON-RPCSample Request:{"version": "1.1","method": "confirmFruitPurchase","id": "194521489","params": [ [ "apple", "orange", "pear" ], 1.123]}{"version": "1.1","result": "done","error": null,"id": "194521489"}
  16. 16. JSON-RPCSample Request:{"version": "1.1","method": "confirmFruitPurchase","id": "194521489","params": [ [ "apple", "orange", "pear" ], 1.123]}Sample Response:{"version": "1.1","result": "done","error": null,"id": "194521489"}
  17. 17. Types of APIs
  18. 18. Types of APIsXML-RPCSOAPJSON-RPC
  19. 19. Types of APIsXML-RPCSOAP Service OrientedJSON-RPC
  20. 20. Types of APIsXML-RPCSOAP Service OrientedJSON-RPCREST Resource Oriented
  21. 21. Types of APIs XML-RPC SOAP Service Oriented JSON-RPC REST Resource OrientedService Oriented architectures are designedto call methods. REST transports resources.
  22. 22. RESTRepresentational State Transfer
  23. 23. Guiding PrinciplesIdentification of resourcesManipulation of resources through theserepresentationsSelf-descriptive messagesHypermedia as the Engine of ApplicationState (HATEOAS)
  24. 24. Identification of resources Individual resources are identified in requests, for example using URIs in web- based REST systems
  25. 25. Identification of resources Individual resources are identified in requests, for example using URIs in web- based REST systems http://api.myapi.com/article/12
  26. 26. Identification of resources Individual resources are identified in requests, for example using URIs in web- based REST systems http://api.myapi.com/article/12 http://api.myapi.com/articles
  27. 27. Identification of resources Individual resources are identified in requests, for example using URIs in web- based REST systems http://api.myapi.com/article/12 http://api.myapi.com/articles http://api.myapi.com/customer/4/order/18
  28. 28. Manipulation of resources
  29. 29. Manipulation of resources GET Return representation of the resource requested
  30. 30. Manipulation of resources GET Return representation of the resource requested PUT Replace representation with new representation, or create if does not exist
  31. 31. Manipulation of resources
  32. 32. Manipulation of resources POST Create a new resource
  33. 33. Manipulation of resources POST Create a new resource DELETE Delete the resource
  34. 34. Self-descriptive messages Each message includes enough information to describe how to process the message For example, the specification of media type through the use of the Content-Type header
  35. 35. Self-descriptive messages Each message includes enough information to describe how to process the message For example, the specification of media type through the use of the Content-Type headerContent-Type: image/jpeg
  36. 36. Self-descriptive messages Each message includes enough information to describe how to process the message For example, the specification of media type through the use of the Content-Type headerContent-Type: image/jpeg <radius>2</radius>Content-Type: application/xml <unit>inches</unit>
  37. 37. Self-descriptive messagesAnother example are the Response Codes: 200 Okay 413 Request Entity Too Large 201 Created 415 Unsupported Media Type 303 See Other 416 Requested Range Not Satisfiable 401 Unauthorized 501 Not Implemented 404 Not Found many others
  38. 38. HATEOAS
  39. 39. HATEOASJust like with HTTP, there is no maintenanceof application state.
  40. 40. HATEOASJust like with HTTP, there is no maintenanceof application state.Cookies are bad! Very, very bad!!
  41. 41. HATEOASJust like with HTTP, there is no maintenanceof application state.Cookies are bad! Very, very bad!!Related URIs should be included inrepresentations of resources.
  42. 42. Live Examples!
  43. 43. Other ways to interact with a REST service
  44. 44. Other ways to interact with a REST serviceOPTIONSDiscover which methods of manipulation areavailable for specified resource
  45. 45. Other ways to interact with a REST serviceOPTIONSDiscover which methods of manipulation areavailable for specified resourceHEADGet sample of Response header without datapayload
  46. 46. Conversation Starters
  47. 47. REST is a set of principles and not a specification
  48. 48. How do you specifyformat of response?
  49. 49. How do you specify format of response?Content-Type header
  50. 50. How do you specify format of response?Content-Type headerParameter passed in the URIhttp://api.myapi.com/orders?format=text/xml
  51. 51. Allow for differing Accept and Content-Type values Content-Type: application/xml Accept: text/javascript
  52. 52. Represent headers in response payloadStatus Code: 200 OKDate: Wed, 16 Mar 2011 17:31:39 GMTVary: AcceptContent-Length: 512Keep-Alive: timeout=5, max=100Connection: Keep-AliveContent-Type: application/xml<?xml version="1.0" encoding="UTF-8"?><response> <headers> <ResponseCode>200</ResponseCode> <Vary>Accept</Vary> </headers> <country> <id>1</id> <name>United States of America</name> <regionCode>US</regionCode> <callingPrefix>011</callingPrefix> <callingCode>1</callingCode> </country></response>
  53. 53. http://www.aisee.com/graph_of_the_month/http.png
  54. 54. Versioning of resources
  55. 55. There are really only two ways to implement the concept of versioning: use of HTTP headers through the syntax of the URI
  56. 56. HTTP HeadersContent-Type: application/vnd.mycompany.myapp+xmlContent-Type: application/vnd.mycompany.myapp2+xmlX-API-Version: 2.0
  57. 57. URI Syntaxapi.mysite.com/articles?version=2api.mysite.com/v2/articles
  58. 58. But what are we really versioning?Representation of our resources?Our application’s business logic?
  59. 59. Should be our application’s businesslogic, but you cannot ignore changesto the resource’s representationeither.
  60. 60. Suggest use of [Major].[Minor].[Revision] api.mysite.com/v1.4.7/articles! ! Major!- change to business process! ! Minor!- change to representationRevision! - syntax corrections
  61. 61. REST API implemented in Zend Framework https://github.com/notmessenger
  62. 62. Thank You Jeremy Brownnotmessenger.com

×