1. A Conversation About REST
Jeremy Brown
notmessenger.com

2. What is an API?

3. What is an API?
From Wikipedia:
An application programming interface (API)
is a particular set of rules and specifications
that a software program can follow to access
and make use of the services and resources
provided by another software program that
implements the API.

4. What is an API?
Wikipedia continues:
It serves as an interface between different
software programs and facilitates their
interaction, similar to the way the user
interface facilitates interaction between
humans and computers.

5. What is an API?
Our understanding:
Set of rules and specifications to facilitate
the interaction between different software
programs.

6. Examples
mkdir
format

7. Types of APIs
XML-RPC (1998)
SOAP (1998, 2003)
JSON-RPC (2005)
REST (2000)

8. XML-RPC
xmlrpc.com
It’s remote procedure calling using HTTP as
the transport and XML as the encoding.
XML-RPC is designed to be as simple as
possible, while allowing complex data
structures to be transmitted, processed and
returned.

9. XML-RPC
xmlrpc.com also says:
We wanted a clean, extensible format that’s very
simple. It should be possible for an HTML coder to
be able to look at a file containing an XML-RPC
call, understand what it’s doing, and be able to
modify it and have it work on the first or second
try... We also wanted it to be an easy protocol
that could quickly be adapted to run in other
environments or on other operating systems.

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

11. XML-RPC
Sample 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. SOAP
SOAP spec:
SOAP is a lightweight protocol for exchange of
information in a decentralized, distributed
environment. It is an XML based protocol that
consists of three parts: an envelope that defines a
framework for describing what is in a message and
how to process it, a set of encoding rules for
expressing instances of application-defined datatypes,
and a convention for representing remote procedure
calls and responses.

13. SOAP
Sample Request:
POST /InStock HTTP/1.1
Host: www.example.org
Content-Type: application/soap+xml; charset=utf-8
Content-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. JSON-RPC
Wikipedia says:
JSON-RPC is a remote procedure call
protocol encoded in JSON. It is a very simple
protocol (and very similar to XML-RPC),
defining only a handful of data types and
commands.

15. JSON-RPC
Sample Request:
{
"version": "1.1",
"method": "confirmFruitPurchase",
"id": "194521489",
"params": [
[ "apple", "orange", "pear" ],
1.123
]
}
{
"version": "1.1",
"result": "done",
"error": null,
"id": "194521489"
}

16. JSON-RPC
Sample 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. Types of APIs

18. Types of APIs
XML-RPC
SOAP
JSON-RPC

19. Types of APIs
XML-RPC
SOAP Service Oriented
JSON-RPC

20. Types of APIs
XML-RPC
SOAP Service Oriented
JSON-RPC
REST Resource Oriented

21. Types of APIs
XML-RPC
SOAP Service Oriented
JSON-RPC
REST Resource Oriented
Service Oriented architectures are designed
to call methods. REST transports resources.

22. REST
Representational State Transfer

23. Guiding Principles
Identification of resources
Manipulation of resources through these
representations
Self-descriptive messages
Hypermedia as the Engine of Application
State (HATEOAS)

24. Identification of resources
Individual resources are identified in
requests, for example using URIs in web-
based REST systems

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. 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. 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. Manipulation of resources

29. Manipulation of resources
GET
Return representation of the resource
requested

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

31. Manipulation of resources

32. Manipulation of resources
POST
Create a new resource

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

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. 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
Content-Type: image/jpeg

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 header
Content-Type: image/jpeg
<radius>2</radius>
Content-Type: application/xml <unit>inches</unit>

37. Self-descriptive messages
Another 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. HATEOAS

39. HATEOAS
Just like with HTTP, there is no maintenance
of application state.

40. HATEOAS
Just like with HTTP, there is no maintenance
of application state.
Cookies are bad! Very, very bad!!

41. HATEOAS
Just like with HTTP, there is no maintenance
of application state.
Cookies are bad! Very, very bad!!
Related URIs should be included in
representations of resources.

43. Live Examples!

44. Other ways to interact
with a REST service

45. Other ways to interact
with a REST service
OPTIONS
Discover which methods of manipulation are
available for specified resource

46. Other ways to interact
with a REST service
OPTIONS
Discover which methods of manipulation are
available for specified resource
HEAD
Get sample of Response header without data
payload

47. Conversation Starters

48. REST is a set of principles
and not a specification

49. How do you specify
format of response?

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

51. How do you specify
format of response?
Content-Type header
Parameter passed in the URI
http://api.myapi.com/orders?format=text/xml

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

53. Represent headers in
response payload
Status Code: 200 OK
Date: Wed, 16 Mar 2011 17:31:39 GMT
Vary: Accept
Content-Length: 512
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-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>

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

55. Versioning of resources

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

57. HTTP Headers
Content-Type: application/vnd.mycompany.myapp+xml
Content-Type: application/vnd.mycompany.myapp2+xml
X-API-Version: 2.0

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

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

60. Should be our application’s business
logic, but you cannot ignore changes
to the resource’s representation
either.

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

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

63. Thank You
Jeremy Brown
notmessenger.com