A Conversation About REST

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/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/articles 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/articles http://api.myapi.com/article/12 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

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

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

Thank You Jeremy Brownnotmessenger.com

A Conversation About REST

by Jeremy Brown on Apr 12, 2011

Accessibility

Categories

Tags

Upload Details

Usage Rights

3 Embeds 3

Statistics

A Conversation About REST — Presentation Transcript

http://localhost	1
http://www.slideshare.net	1
http://paper.li	1