A Conversation About REST - Extended Version

1,340 views

Published on

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

No Downloads
Views
Total views
1,340
On SlideShare
0
From Embeds
0
Number of Embeds
5
Actions
Shares
0
Downloads
43
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide
  • \n
  • \n
  • \n
  • \n
  • \n
  • SOAP - 2003: W3C recommendation submitted. Is NOT a spec.\n
  • \n
  • \n
  • \n
  • \n
  • Can be used over SMTP and other protocols because of its design.\n\nIs NOT lightweight.\n\nNothing works out of the box - ever.\n
  • \n
  • \n
  • Required Methods\n\nREQUEST:\n method\n id\n params\n\nRESPONSE:\n result\n error\n id\n
  • \n
  • \n
  • \n
  • \n
  • Roy Fielding\n\nCo-authored HTTP 1.0 and 1.1 spec\n\nREST was designed along side HTTP 1.1\n
  • \n
  • 2nd one: talk about collections\n\n3rd one: talk about customer/order vs order/customer\n
  • 2nd one: talk about collections\n\n3rd one: talk about customer/order vs order/customer\n
  • 2nd one: talk about collections\n\n3rd one: talk about customer/order vs order/customer\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • Remember PUT? Not all APIs create a new resource.\n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • \n
  • Order a book\n-----------\nUsed to not get a receipt, but now you do.\nIs a change to the business rules.\nAccomplished by a “303 See Other” header.\nNo big deal.\n\nPurchasing system\n----------------\nUsed to get back a representation that contained order details, including invoice number.\nNow ability to select payment options is what is served instead (PO #, net 30, etc).\nIs a change to the business rules.\nConsuming client *should* know how to follow links and if just computer-to-computer would be fine.\nBut if GUI, then new user experience needs to be developed.\n\nAddition of email address to customer details\n--------------------------------------\nHad name and phone before.\nNow have added email.\n\n
  • \n
  • \n
  • \n
  • 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

    ×