This document provides an overview of REST (REpresentational State Transfer) and developing REST APIs in Symfony2. It discusses the history and architectural constraints of REST, including being client-server, stateless, cacheable, layered, and having a uniform interface. It also covers REST maturity levels, content negotiation, HTTP methods and status codes, and the HATEOAS principle of providing hypermedia controls. The document concludes by stating it will continue discussing developing REST APIs in Symfony2 in future parts.

1. Service approach for
development Rest API in
Symfony2
Aleksey Kryvtsov @ Web-developer at CPCS
alkryvtsov@gmail.com

2. REST
REpresentational State Transfer
PART 1

3. HISTORY
REST was defined by Roy Thomas Fielding in 2000
In his dissertation "Architectural Styles and the Design of
Network - based Software Architectures"
3

4. ● Client - server
● Stateless
● Cacheable
● Layered system
● Uniform interface:
○ Identification of resources
○ Manipulation of resources through these representations
○ Self-descriptive messages
○ Hypermedia as the engine of application state (HATEOAS)
ARCHITECTURAL CONSTRAINTS
4

5. CLIENT - SERVER | STATELESS
5

6. CACHEABLE
Unsafe methods
Safe methods
GET /articles/1234 HTTP/1.1 - example of safe method
PUT /articles/1234 HTTP/1.1 - example of unsafe method
6

7. CACHING PROCESS
GET /articles/1234 HTTP/1.1
- The resource is not cached yet
- Send request to the API
- Store response in cache and return
GET /articles/1234 HTTP/1.1
- The resource is cached
- Return response from cache
PUT /articles/1234 HTTP/1.1
- Unsafe method, send to API
PURGE /articles/1234 HTTP/1.1
- API sends PURGE method to the
cache
- The resources is removed from the
cache
GET /articles/1234 HTTP/1.1
- The resource is not cached yet
- Send request to the API
- Store response in cache and return
7

8. LAYERED SYSTEM
GET /article/1234 HTTP/1.1
8

9. Identification of resources
GET /article/1234 HTTP/1.1
9

10. Manipulation of resources through these representations
{"Title": "Your title", "Text": "Your text"}
{"id": 1, "Title": "Your title", "Text": "Your text"}
JSON
POST /articles HTTP/1.1
10

11. 11
Self-descriptive messages
Request:
GET /articles/1234 HTTP/1.1
Host: test.host.com
User-Agent: Mozilla/5.0
Accept: application/json
Connection: close
(empty line)
11
Server Response:
HTTP/1.1 200 OK
Date: Wed, 16 Mar 2016 11:20:59 GMT
Server: Apache
Content-Language: ru
Content-Type: application/json;
charset=utf-8
Content-Length: 1234
Connection: close
(empty line)
(json representation)

12. BENEFITS
● Reliability
● Performance
● Scalability
● Simplicity
● Portability
● Modifiability
● Visibility
12

13. REST design maturity levels
(Richardson Maturity Model)
13

14. /index.php?controller=page&action=getarticleid=5
/article/5/4/6/size/media/image?page=2
Level 0
Cacheable ? Scalable ? Readable ? Simplicity ?
Modifiability ? Visibility ?
14

15. GET /articles HTTP/1.1
We want all articles
GET /articles/5/photos/4/comments/1 HTTP/1.1
We want the first comment of the fourth photo for the fifth article
GET /articles/5/photos/4/comments?page=1&limit=10
We want all comments of the fourth photo for the fifth article
Level 1 - Resources
15

16. GET, OPTIONS, HEAD
POST, PUT, PATCH, LINK, UNLINK
DELETE
Level 2 - HTTP verbs
16

17. Manipulation of Resources CRUD to HTTP
verb mapping
Create = POST
Retrieve = GET
Update = PUT (or PATCH)
Delete = DELETE
17

18. Overview of (some) HTTP methods
HTTP Method Safe Idempotent
GET yes yes
HEAD yes yes
PUT no yes
POST no no
DELETE no yes
PATCH no no
18

19. HTTP Status Codes. Part I
HTTP Code Message Description
200 OK The request was processed and returned successfully. Nothing was
changed.
201 Created The new resource was created successfully
400 Bad Request Problem with the request, such as a missing, invalid or type mismatched
parameter
401 Unauthorized The request did not have valid authorization credentials
403 Forbidden Private data you are not allowed to access, or you've hit a rate limit.
404 Not Found Your URL is wrong, or the requested resource doesn't exist
500 Server Error If this persists please contact support. We log and review all errors but your
help often helps us fix it quicker.
19

20. HTTP Status Codes. Part II
Code range Message Description
1xx Information 100 - Continue
2xx Successful 201 - Created
3xx Redirection 301 - Moved Permanently
4xx Client Error 404 - Not Found
5xx Server Error 501 - Not Implemented
20

21. POST /articles HTTP/1.1
{ “title”: “Title” }
GET /articles/1 HTTP/1.1
{ “id”: 1, “title”: “Title” }
PATCH /articles/1 HTTP/1.1
{ “title”: “Title - 1” }
DELETE /articles/1 HTTP/1.1
{ “message”: “Article was deleted” }
Example
21

22. Server Response:
HTTP/1.1 201 Created
Response to a successful request
22
{
"id" : 12,
"subject" : "I have a question!",
"summary" : "Hi, ....",
"customer" : {
"name" : "Bob"
},
"assignedUser": {
"id" : 42,
"name" : "Jim",
// ...

23. Server Response:
HTTP/1.1 500 Server Error
Server: Apache
Content-Language: ru
Content-Type: application/json; charset=utf-8
Errors: Useful error message
23
{
"code" : 1234,
"message" : "Something bad happened :(",
"description" : "More details about the error here",
"documentation" : "http://somehost.api/errors/1234"
}

24. Server Response:
HTTP/1.1 400 Bad Request
Errors: Validation errors for PUT, PATCH and POST
24
{
"code" : 1024,
"message" : "Validation Failed",
"errors" : [
{
"code" : 5432,
"field" : "first_name",
"message" : "First name cannot have fancy characters"
},
{
"code" : 5622,
"field" : "password",
"message" : "Password cannot be blank"
}
//...

25. An important concept developing the REST API is the
Content Negotiation.
GET /api/v1/pages/10.html HTTP/1.1
GET /api/v1/pages/10.json HTTP/1.1
GET /api/v1/pages/10.xml HTTP/1.1
Content Negotiation
25

26. Content negotiation is a mechanism defined in the HTTP specification that
makes it possible to serve different versions of a document (or more generally, a
resource representation) at the same URI, so that user agents can specify which
version fit their capabilities the best.
Content Negotiation. Definition
GET /api/v1/pages/10 HTTP/1.1
Accept: application/json
Accept: application/xml
Accept: text/html
26

27. The user agent provides an Accept HTTP header that lists
acceptable media types and associated quality factors. The
server is then able to supply the version of the resource that
best fits the user agent's needs.
Content Negotiation. Quality factors
Accept: application/json; q=1.0, application/xml; q=0.8,
text/html; q=0.6, text/*; q=0.1
27

28. HATEOAS - Hypermedia As The Engine Of Application State
Level 3 - Hypermedia Controls
The point of hypermedia controls is that they tell us what we can do next, and
the URI of the resource we need to manipulate to do it.
● Use links to allow clients to discover locations and operations
● Link relations are used to express options
● Clients do not need to know URLs
● This controls the state
28

29. Level 3 - HATEOAS: Links and relations
<articles>
<article>
<id>1</id>
<title>Title - 1</title>
<link href="http://example.com/articles/1" rel="self" />
<link href="http://example.com/articles/1/catalogs"
rel="catalogs" />
</article>
<article>
<id>2</id>
<title>Title - 2</title>
<link href="http://example.com/articles/2" rel="self" />
<link href="http://example.com/articles/2/catalogs"
rel="catalogs" />
</article>
<link href="http://example.com/articles?page=1" rel="prev" />
<link href="http://example.com/articles?page=2" rel="self" />
<link href="http://example.com/articles?page=3" rel="next" />
29

30. Level 3 - HATEOAS: Media types
The second part is about adding media types to answer the
question: What?. What is this resource? What does it contain
or what do I need to create such a resource?
This part introduces your own content type:
Content-Type: application/vnd.yourname.something+xml
30

31. Level 3 - HATEOAS: Version
First, you can add the version number in your URIs, this is the
easy way:
/api/v1/users
You can use your new content type:
application/vnd.acme.pave-v1+xml
31

32. Development Rest API in Symfony2
32

33. To be continued...

34. References
https://ru.wikipedia.org/wiki/REST
Wiki
http://restcookbook.com
REST CookBook
http://restful-api-design.readthedocs.org/en/latest/
Thoughts on RESTful API Design
http://www.crummy.com/writing/speaking/2008-QCon/act3.html
Leonard Richardson The Maturity Heuristiс
http://martinfowler.com/articles/richardsonMaturityModel.html
Richardson Maturity Model
http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
Best Practices for Designing a Pragmatic RESTful API
34

35. Thank you
Questions ?
Aleksey Kryvtsov alkryvtsov@gmail.com
35