A REST API involves more than just pushing data back and forth between endpoints. This presentation will explain what REST is and also present a variety of topics and questions you will certainly come across while implementing your API. By Jeremy Brown @notmessenger http://notmessenger.com

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/articles

26. Identification of resources
Individual resources are identified in
requests, for example using URIs in web-
based REST systems
http://api.myapi.com/articles
http://api.myapi.com/article/12

27. Identification of resources
Individual resources are identified 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

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. Allow for differing Accept
and Content-Type values
Content-Type: application/xml
Accept: text/javascript

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

51. Thank You
Jeremy Brown
notmessenger.com