The document discusses Representational State Transfer (REST). It defines REST as changing resource state through transferring resource representations. Key REST concepts discussed include resources and their representations, Uniform Resource Identifiers (URIs), and Hypermedia as the Engine of Application State (HATEOAS). The document provides examples of resource modeling and implementing RESTful APIs using HTTP and Symfony frameworks. It emphasizes designing APIs around resources and representing state transitions through hypermedia controls.

1. REpresentational State
Transfer
GET https://PUG.at.dp.ua/representational-state-transfer HTTP/1.1
Dmytro Krasun, TonicForHealth, Kyiv

2. Agenda
1. REST ideas.
2. REST and HTTP.
3. Symfony and HTTP.

3. Hype cycle

4. REST and RPC

5. rest in peace

6. REST API

7. Idea

8. How often you cry about refactoring?

9. REpresentational State Transfer
Is about changing resource state through transferring resource representations.
Key concepts:
Resources and resource representations;
URI;
HATEOAS.

10. Resources and resource representations
“The key abstraction of information in REST is a resource. Any information that
can be named can be a resource: a document or image, a temporal service (e.g.
"today's weather in Los Angeles"), a collection of other resources, a non-virtual
object (e.g. a person), and so on. In other words, any concept that might be the
target of an author's hypertext reference must fit within the definition of a resource.
A resource is a conceptual mapping to a set of entities, not the entity that
corresponds to the mapping at any particular point in time.” - Roy Fielding’s
dissertation.

11. Resource and resource representations
Account ($1 500) is resource, but:
<ul class=”account”><li class=”currency”>USD</li><li class=”balance”>1500</li></ul>;
{“balance”: 1500};
{“balance”: 1500, “currency”: “USD”};
<account><balance currency=”USD”>1500</balance></account>;
<account currency=”USD” balance=”1500” />
Are different Account (read as resource) representations.

12. Uniform Resource Identifier
Uniform? Yes, not unique.
Resource can have more than one URI.
Examples: “james.bond”, “j.bond”, “007-company”.
URL (Uniform Resource Locator) as URI in HTTP:
Can be used as URI;
Valid URLs’: “http://james.bond”, “http://j.bond”, “ftp://zero-zero-
seven.com/docs.txt”.

13. “RESTful” URL
1. http://example.com/users/1?delete
2. http://example.com/delete-users/1
3. http://example.com/?userId=1&action=delete
4. http://example.com/getData?userId=1
5. http://example.com/users/1
6. http://example.com/user/1

14. What is really URL?

15. What is really URL?

16. Hypermedia as the Engine of Application State
Client interacts with an application entirely through hypermedia provided
dynamically.
Resource state machines.

17. Hypermedia as the Engine of Application State

18. It’s important
- Reliability (no need to store information about client which can be corrupted
or lost);
- Performance (cache);
- Scalability;
- Simplicity of interfaces;
- Ability to evolve and adapt to new requirements (WWW as example).

19. Implementation

20. HTTP as “framework”
HTTP verbs (POST, GET, DELETE and so on) for resource manipulations;
URL as URI for resource;
Request and response bodies for resource representations;
Status codes;
Headers (for more precise control):
Caching;
Authentication and authorization;
Versioning (E-Tag);

21. Transfer resource state

22. Early stage adopters
It’s very hard to implement REST in the right way.
Some of closest implementations: Github API, Amazon S3 REST API, JIRA
REST API.
Github API (https://developer.github.com/v3/repos/forks/):
HATEOAS (links to other resources);
Right granularity (POST /repos/:owner/:repo/forks);
Right status codes (202 Accepted for POST /repos/:owner/:repo/forks).

23. Standards
1. HTTP, URI, URI Template, JSON, XML, HTML and friends;
2. HAL - http://stateless.co/hal_specification.html;
3. Siren - https://github.com/kevinswiber/siren.

24. Resource modeling
is key problem.*
* There is no silver bullet :( **
** That’s why we earn money, because of thinking, so :)

25. 1. I want to deposit money to account
We have account and account balance. Possible representation:
GET /accounts/{accountId}
{“account”: {“balance”: 1500, “currency”: “USD”}}

26. 1. I want to deposit money to account
PUT /accounts/{accountId}
{“balance”: 1500, “currency”: “USD”}
Hmmm…
It’s better to PATCH /accounts/{accountId}
[{“op”: “replace”, “path”: “/balance”, “value”: 1500}]

27. 1. I want to deposit money to account
Yes, it’s better to create transaction. Transaction is also resource.
POST /accounts/usd/transactions (Hey! why not
“/accounts/{accountId}/transactions”?
{“amount”: “1500”}
So now:
1. We can get the state of current transaction: GET /accounts/1/transactions/23
-> {“status”: “pending”}.
2. We have natural log of account operations.

28. 2. I want to copy something (account, ad campaign
and so on)
Copy & paste pattern: I can GET it, and POST it.

29. 2. I want to copy something (account, ad campaign
and so on)
Amazon S3 solution:
http://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectCOPY.html

30. 2. I want to copy something
We have resource copying process or resource copier. And we can send resource
representation to it.
{
“title”: “some ad campaign”,
“_links”: {“copy”: “http://somesite.org/campaigns/1/copy”}
}
POST:
1. /campaigns/{campaignId}/copiers, /campaigns/{surveyId}/campaigns
2. /campaign-copier with {“surveyId”: 1}

31. 3. I want to sort something
Easy-peasy!
POST /ad-campaigns/{campaignId}/sortings
{“previousCampaignId”: 42}
Because you need to satisfy too many conditions.

32. 4. I want to update one field in very big resource
It’s better to have 5-7 small resources which easier to update and control, than
something big.
OK! We can solve it:
PUT /ad-campaign/1/meta
{ “title”: “new title”, … and other fields}

33. Symfony speaks HTTP
REST ~ HTTP ~ Symfony

34. Resources
Entity or set of entities, e. g. “Ad
Campaign” entity in marketing
application;
Service or set of services, e. g.
“Copier” service, which can
copy anything;
Any operation on a resource be
modeled as “process”
resource.
Any business entity or business
process can be modeled as
resource.

35. Resource
representations

36. Resource representation handlers

37. HATEOAS (https://github.com/willdurand/Hateoas)

38. HATEOAS

39. Links
1. REST bundle documentation (https://bitbucket.org/tonicforhealth/server-
bundle-rest-
bundle/src/master/Resources/doc/index.md?at=master&fileviewer=file-view-
default).
2. “REST in Practice, Hypermedia and Systems Architecture“ by Jim Webber,
Savas Parastatidis, Ian Robinson
(http://shop.oreilly.com/product/9780596805838.do).
3. “REST API Design - Resource Modeling”
(https://www.thoughtworks.com/insights/blog/rest-api-design-resource-
modeling).