Are you confused by REST APIs? Can't tell a PUT from a POST? No idea what a non-idempotent operation is? Despite their ubiquity, the details of what makes an API RESTful are often lost even on experienced developers. We'll cover the basics of the HTTP protocol that drives most REST services, break down the lingo, and clear up some misconceptions about this powerful and popular methodology.

1. Demystifying the
REST API
Samantha Quiñones (@ieatkillerbees)

2. @ieatkillerbees
http://samanthaquinones.com

4. Engineer
A person who designs, builds, or
maintains things.

5. Pattern
A model or design used to guide the
building of things.

6. REST
(Representational State Transfer)
An architectural pattern for distributed
hypermedia systems.

7. REST[ful] API
A resource-oriented API built to conform
with the REST architectural pattern.

8. Hypermedia
A non-linear medium of many disparate types of
information, including text, images, video, audio
and hypertext.

9. I’m not here to tell you…
How to Build an API

10. -Roy Fielding, REST Discussion Mailing List
“[T]he goal of my dissertation is to teach people how
to think about the problem in terms of trade-offs, not
in terms of rigid repetition…”

11. Nothing is more easy than to reduce this mass to one
quarter of its bulk. You know that curious cellular
matter which constitutes the elementary tissues of
vegetable? This substance is found quite pure in many
bodies, especially in cotton, which is nothing more than
the down of the seeds of the cotton plant. Now cotton,
combined with cold nitric acid, become transformed into
a substance eminently insoluble, combustible, and
explosive. It was first discovered in 1832, by Braconnot, a
French chemist, who called it xyloidine. In 1838 another
Frenchman, Pelouze, investigated its different properties,
and finally, in 1846, Schonbein, professor of chemistry at
Bale, proposed its employment for purposes of war. This
powder, now called pyroxyle, or fulminating cotton, is
prepared with great facility by simply plunging cotton
for fifteen minutes in nitric acid, then washing it in
water, then drying it, and it is ready for use.

12. Nothing is more easy than to reduce this mass to one
quarter of its bulk. You know that curious cellular
matter which constitutes the elementary tissues of
vegetable? This substance is found quite pure in many
bodies, especially in cotton, which is nothing more than
the down of the seeds of the cotton plant. Now cotton,
combined with cold nitric acid, become transformed into
a substance eminently insoluble, combustible, and
explosive. It was first discovered in 1832, by Braconnot, a
French chemist, who called it xyloidine. In 1838 another
Frenchman, Pelouze, investigated its different properties,
and finally, in 1846, Schonbein, professor of chemistry at
Bale, proposed its employment for purposes of war. This
powder, now called pyroxyle, or fulminating cotton, is
prepared with great facility by simply plunging cotton
for fifteen minutes in nitric acid, then washing it in
water, then drying it, and it is ready for use.

13. NASA/JPL-Caltech

14. The REST
Architectural Style

15. © Henry Story, 2007 (CC BY-NC 2.0)

16. Architectural Styles and the Design of
Network-based Software Architectures
Roy T. Fielding
(http://www.ics.uci.edu/~fielding/pubs/dissertation/faq.htm)

17. MySQL
PHP 5.6
NGINX
Symfony 2 RabbitMQ

18. WWW
Null Style

19. Client-Server Architecture
ServerClient

20. Statelessness
ServerClient
Client
Client

21. Cache
ServerClient
Client
Client

22. Uniform Interface
Server
Client
Client
Client
Server
R
R
S
H
R
R
S
H

23. Layered System
Server
Client
Client
Client
Server
R
R
S
H
R
R
S
H
Gateway
Proxy

24. Code On Demand
Server
Client
Client
Client
Server
R
R
S
H
R
R
S
H
Gateway
Proxy

25. The Uniform Interface

26. Resource
A thing, or a collection of things that…
May be concrete, or abstract…
May be static, or vary over time…
Has a name that is unique…
Uniform Interface

27. Uniform Interface

28. Resource Identifier
A unique name which is…
A conceptual mapping to a resource…
Or a collection of resources…
Uniform Interface

29. http://galaxies.tembies.com/groups/local/galaxies/ngc4258.json
“The most recent 10 tweets containing the hashtag ‘#MWPHP’”
Uniform Interface

30. Representation
A sequence of bytes that…
Contains the state of a resource…
Consists of data…
Metadata about the data…
Metadata about the metadata…
Uniform Interface

31. {
"name": "Messier 106",
"ngc_id": 4258,
"type": "SAB(s)bc",
"size": 135000
}
Uniform Interface

32. Content-Type: application/json
{
"name": "Messier 106",
"ngc_id": 4258,
"type": "SAB(s)bc",
"size": 135000
}
Uniform Interface

33. Content-Type: application/json
Cache-Control: max-age=3600 public
{
"name": "Messier 106",
"ngc_id": 4258,
"type": "SAB(s)bc",
"size": 135000
}
Uniform Interface

34. Self-Contained Messages
Contains all information necessary to…
Process the request…
Return an appropriate representation…
Uniform Interface

35. Hypermedia
As
The
Engine
Of
Application
State

36. <galaxy>
<ngc_id>4258</ngc_id>
<name/>Messier 106</name>
<type>SAB(s)bc</type>
<size>135000</size>
<link rel="group" href="/groups/local" />
<link rel="self"
href="/groups/local/galaxies/ngc4258" />
</galaxy>

37. Hypermedia Formats
HTML XML
CSS Atom

38. JSON is not a
Hypermedia Format

39. JSON Hypermedia
Collection
+JSON
JSON-LD
JSON:API UBER
JSON+HAL

40. Hypertext Application Language
A proposed (2012) standard that…
Expresses relationships between resources…
Supports JSON (JSON+HAL)…
Supports XML (XML+HAL)…

41. {
"name": "Messier 106",
"ngc_id": 4258,
"type": "SAB(s)bc",
"size": 135000,
"_links": {
"self": { "href": "/groups/local/galaxies/ngc4258" } },
"group": { "href": "/groups/local" } }
}
}

42. HTTP
(Hyper Text Transport Protocol)

43. Version 0.9 (1991)
Version 1.0 (1996)
Version 1.1 (1999)

44. GET
POST
OPTIONS
HEAD
DELETE
TRACE
PUT
PATCH
CONNECT

45. Idempotent
UnsafeSafe
GET POST
OPTIONS
HEAD
DELETE
TRACE
PUT PATCH
CONNECT

46. Idempotence
A property of an operation that can be
applied multiple time without changing
the result, such that ƒ(ƒ(𝑥)) = ƒ(𝑥)

47. GET
Request the representation of a resource
with a given identifier
SafeIdempotent

48. GET /groups/local/galaxies/ncg4258 HTTP/1.1
Host: galaxies.tembies.com
Content-Type: application/json; charset=UTF-8

49. HTTP/1.1 200 OK
Content-Length: 207
Content-Type: application/json; charset=UTF-8
{
"name": "Messier 106",
"ngc_id": 4258,
"type": "SAB(s)bc",
"size": 135000,
"_links": {
"self": { "href": "/groups/local/galaxies/ngc4258" } },
"group": { "href": "/groups/local" } }
}
}

50. HEAD
Request the representation metadata and
control data for a resource with a given
identifier
SafeIdempotent

51. GET /groups/local/galaxies/ncg4258 HTTP/1.1
Host: galaxies.tembies.com
Content-Type: application/json; charset=UTF-8

52. HTTP/1.1 200 OK
Content-Length: 207
Content-Type: application/json; charset=UTF-8

53. TRACE
Request the server respond by echoing
the request.
SafeIdempotent

54. TRACE /groups/local/galaxies/ncg4258 HTTP/1.1
Host: galaxies.tembies.com
Content-Type: application/json; charset=UTF-8

55. HTTP/1.1 200 OK
Content-Type: message/http
Content-Length: 39
TRACE /groups/local/galaxies/ncg4258 HTTP/1.1
Host: galaxies.tembies.com
Content-Type: application/json; charset=UTF-8

56. OPTIONS
Request the server respond with
information about what methods are
allowed for a resource.
SafeIdempotent

57. OPTIONS /groups/local/galaxies/ncg4258 HTTP/1.1
Host: galaxies.tembies.com
Content-Type: application/json; charset=UTF-8

58. HTTP/1.1 200 OK
Content-Type: message/http
Content-Length: 39
Allow: GET,HEAD,DELETE,POST,OPTIONS,TRACE

59. DELETE
Request the server delete the resource.
UnsafeIdempotent

60. DELETE /groups/local/galaxies/ncg4258 HTTP/1.1
Host: galaxies.tembies.com
Content-Type: application/json; charset=UTF-8

61. HTTP/1.1 204 No Content

62. PUT
Request the server store a provided
representation of a resource at the
specified name, replacing the existing
resource if it exists.
UnsafeIdempotent

63. PUT /groups/local/galaxies/ncg4258 HTTP/1.1
Host: galaxies.tembies.com
Content-Type: application/json; charset=UTF-8
{
"name": "Messier 106",
"ngc_id": 4258,
"type": "SAB(s)bc",
"size": 135000,
“example_type": "contrived",
"_links": {
"self": { "href": "/groups/local/galaxies/ngc4258" } },
"group": { "href": "/groups/local" } }
}
}

64. HTTP/1.1 204 No Content

65. POST
Request the server store a provided
representation of a resource as a new
member of the collection identified by
the resource name
UnsafeNot Idempotent

66. POST /groups/local/galaxies HTTP/1.1
Host: galaxies.tembies.com
Content-Type: application/json; charset=UTF-8
{
"name": "Messier 51a",
"ngc_id": 5194,
"type": “SA(s)bc pec",
"size": 60000,
}

67. HTTP/1.1 201 Created
Location: /groups/local/galaxies/ngc4258
{
"_links": {
"self": { "href": "/groups/local/galaxies/ngc4258" } }
}
}

68. PUT vs POST
or
How Yelling Loudly Can Make a
Difference

69. PUT
Create or replace…
a Resource or collection
Can be repeated…
safely
POST
Append to a
collection
Can not be repeated…
safely

70. Idempotency
ServerClient
PUTPUTPUT

71. Idempotency
ServerClient
POSTPOSTPOST

72. Antipattern
A common solution to an engineering
problem that is, at best ineffective,
and at worst, potentially destructive.

73. Overloading GET (or POST)
GET /things/42?action=delete
GET /widgets/42/delete
GET /widgets/delete?id=42
Antipattern

74. Abusing Status Codes
HTTP/1.1 200 OK
{
"success": false,
"code": "ID10T",
"message": "Tweet @jakeasmith for lols"
}
Antipattern

75. Abusing Status Codes
Antipattern
1xx - Informational
2xx - Success
3xx - Redirection
4xx - Client Error
5xx - Server Error

76. Relying on Session
REST APIs are Stateless
Antipattern

77. Not Supporting Caching
Learn to use cache headers
Antipattern

78. Your Humble Speaker’s Loud
and Oft-Repeated Advice

79. Sanitize Assumptions
Patterns like REST make assumptions safer.
The further you are from the consumers of
your API, the closer you should adhere to
the pattern.
Advice

80. Avoid Side-Effects
GET is a safe method. GET should
never, never, cause side effects.
Advice

81. Document your APIs
REST APIs are self-documenting.
That’s a feature, not an excuse.
Advice

82. Understand When REST Works
Resource (noun) oriented
CRUD
Open consumption
Open formats
Advice

83. And When It Doesn’t
Action (verb) oriented
RPC
Closed consumption
Closed formats
Advice

84. After the Conference

85. Give Me Some Feedback!
https://joind.in/13067

86. Read the Dissertation
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

87. Read the RFC
https://www.ietf.org/rfc/rfc2616.txt

88. Learn about Caching
http://www.mobify.com/blog/beginners-guide-to-http-cache-headers/

89. Check Out Some Documentation
Frameworks
RAML - http://raml.org
API Blueprint - http://apiblueprint.org
Swagger - http://swagger.io

90. Consider Some Further Reading
Build APIs You Won't Hate by Phil Sturgeon
RESTful Web Services by Leonard Richardson & Sam Ruby

91. Build an Awesome API
Easy to maintain
Meets your needs
Solves a problem

92. Tell Your Community
how you built it
at a user group or a
conference

93. Other Resources
• RFC 2616 “Hypertext Transfer Protocol” (http://bit.ly/LkW6OW)
• RFC 5789 “PATCH Method for HTTP” (http://bit.ly/1cFpvtq)
• JSON HAL Proposal (http://bit.ly/1kJLvgw)
• RFC 6902 “JSON PATCH” (http://bit.ly/LkWyww)
• Fielding’s Dissertation (http://bit.ly/1eTY8AI)
• REST Cookbook (http://restcookbook.com)
• HATEOAS for PHP: http://hateoas-php.org/
• Well-supported, Symfony-ready HATEOAS library
• REST APIs with Symfony2: The Right Way (http://williamdurand.fr/2012/08/02/rest-apis-with-symfony2-the-right-way/)