A Conversation About REST - Extended Version

A Conversation About REST Jeremy Brown notmessenger.com

What is an API?

What is an API?From Wikipedia:An application programming interface (API)is a particular set of rules and speciﬁcationsthat a software program can follow to accessand make use of the services and resourcesprovided by another software program thatimplements the API.

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.

What is an API?Our understanding:Set of rules and speciﬁcations to facilitatethe interaction between different softwareprograms.

Examplesmkdirformat

Types of APIsXML-RPC (1998)SOAP (1998, 2003)JSON-RPC (2005)REST (2000)

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.

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 ﬁle containing an XML-RPCcall, understand what it’s doing, and be able tomodify it and have it work on the ﬁrst or secondtry... We also wanted it to be an easy protocolthat could quickly be adapted to run in otherenvironments or on other operating systems.

XML-RPCSample Request:<?xml version="1.0"?><methodCall> <methodName>getStateName</methodName> <params> <param> <value><int>40</int></value> </param> </params></methodCall>

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>

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 deﬁnes aframework for describing what is in a message andhow to process it, a set of encoding rules forexpressing instances of application-deﬁned datatypes,and a convention for representing remote procedurecalls and responses.

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>

JSON-RPCWikipedia says:JSON-RPC is a remote procedure callprotocol encoded in JSON. It is a very simpleprotocol (and very similar to XML-RPC),deﬁning only a handful of data types andcommands.

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"}

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"}

Types of APIs

Types of APIsXML-RPCSOAPJSON-RPC

Types of APIsXML-RPCSOAP Service OrientedJSON-RPC

Types of APIsXML-RPCSOAP Service OrientedJSON-RPCREST Resource Oriented

Types of APIs XML-RPC SOAP Service Oriented JSON-RPC REST Resource OrientedService Oriented architectures are designedto call methods. REST transports resources.

RESTRepresentational State Transfer

Guiding PrinciplesIdentiﬁcation of resourcesManipulation of resources through theserepresentationsSelf-descriptive messagesHypermedia as the Engine of ApplicationState (HATEOAS)

Identiﬁcation of resources Individual resources are identiﬁed in requests, for example using URIs in web- based REST systems

Identiﬁcation of resources Individual resources are identiﬁed in requests, for example using URIs in web- based REST systems http://api.myapi.com/article/12

Identiﬁcation of resources Individual resources are identiﬁed in requests, for example using URIs in web- based REST systems http://api.myapi.com/article/12 http://api.myapi.com/articles

Identiﬁcation of resources Individual resources are identiﬁed 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

Manipulation of resources

Manipulation of resources GET Return representation of the resource requested

Manipulation of resources GET Return representation of the resource requested PUT Replace representation with new representation, or create if does not exist

Manipulation of resources

Manipulation of resources POST Create a new resource

Manipulation of resources POST Create a new resource DELETE Delete the resource

Self-descriptive messages Each message includes enough information to describe how to process the message For example, the speciﬁcation of media type through the use of the Content-Type header

Self-descriptive messages Each message includes enough information to describe how to process the message For example, the speciﬁcation of media type through the use of the Content-Type headerContent-Type: image/jpeg

Self-descriptive messages Each message includes enough information to describe how to process the message For example, the speciﬁcation of media type through the use of the Content-Type headerContent-Type: image/jpeg <radius>2</radius>Content-Type: application/xml <unit>inches</unit>

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 Satisﬁable 401 Unauthorized 501 Not Implemented 404 Not Found many others

HATEOAS

HATEOASJust like with HTTP, there is no maintenanceof application state.

HATEOASJust like with HTTP, there is no maintenanceof application state.Cookies are bad! Very, very bad!!

HATEOASJust like with HTTP, there is no maintenanceof application state.Cookies are bad! Very, very bad!!Related URIs should be included inrepresentations of resources.

Live Examples!

Other ways to interact with a REST service

Other ways to interact with a REST serviceOPTIONSDiscover which methods of manipulation areavailable for speciﬁed resource

Other ways to interact with a REST serviceOPTIONSDiscover which methods of manipulation areavailable for speciﬁed resourceHEADGet sample of Response header without datapayload

Conversation Starters

REST is a set of principles and not a speciﬁcation

How do you specifyformat of response?

How do you specify format of response?Content-Type header

How do you specify format of response?Content-Type headerParameter passed in the URIhttp://api.myapi.com/orders?format=text/xml

Allow for differing Accept and Content-Type values Content-Type: application/xml Accept: text/javascript

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>

http://www.aisee.com/graph_of_the_month/http.png

Versioning of resources

There are really only two ways to implement the concept of versioning: use of HTTP headers through the syntax of the URI

HTTP HeadersContent-Type: application/vnd.mycompany.myapp+xmlContent-Type: application/vnd.mycompany.myapp2+xmlX-API-Version: 2.0

URI Syntaxapi.mysite.com/articles?version=2api.mysite.com/v2/articles

But what are we really versioning?Representation of our resources?Our application’s business logic?

Should be our application’s businesslogic, but you cannot ignore changesto the resource’s representationeither.

Suggest use of [Major].[Minor].[Revision] api.mysite.com/v1.4.7/articles! ! Major!- change to business process! ! Minor!- change to representationRevision! - syntax corrections

REST API implemented in Zend Framework https://github.com/notmessenger

Thank You Jeremy Brownnotmessenger.com

A Conversation About REST - Extended Version

by Jeremy Brown on Jul 13, 2011

Accessibility

Categories

Tags

Upload Details

Usage Rights

Statistics

A Conversation About REST - Extended Version — Presentation Transcript