Доклад об уровнях REST и принципе HATEOAS на KharkivJS 7 ноября 2015

1. REST и HATEOAS
1

2. REST и HATEOAS
2
Доклад не из будущего

3. Артём Бей
@defly_self
Fullstack dev в Trinity Mirror
3

4. REST != HTTP

5. Representational State Transfer
"Architectural Styles and
the Design of Network-based Software Architectures”
Roy Fielding
5

6. REST — это архитектурный
стиль для распределенных
гипермедиа систем.
6

7. Ресурс
http://…/resource
<xml>
<entity/>
</xml>
{
entity: {…}
}
7

8. http://…/resource
<xml>
<entity/>
</xml>
{
entity: {…}
}
представление
представление
ресурс
идентификатор
документ
картинка
процесс
…
8

9. Richardson Maturity Model
9

10. REST уровня 0
POST /api
{
"do": "createOrder",
"params": {
"count": 2
}
}
POST /api
{
"do": "cancelOrder",
"params": {
"id": "34xzfha834flksd34"
}
}
200 OK
{
"success": true,
"res": {
"id": "f239sdk237sdf438"
}
}
200 OK
{
"success": false,
"error": {
"code": 666,
"message": "because fk u thats why"
}
}
/api
10

11. REST уровня 1
POST /users
{…}
200 OK
{
"success": true,
"res": {
"id": "f239sdk237sdf438"
}
}
200 OK
{
"success": false,
"error": {
"code": 40000,
"message": "today is
a bad day"
}
}
/users
POST /users/1
{…}
POST /orders
{…}
/users/1
/orders
11

12. Tesla Model S использует REST Level 1

13. REST уровня 2
13

14. REST уровня 2
Используем HTTP по спецификации
14

15. Методы
GET
POST
PUT
DELETE
OPTIONS
HEAD
PATCH
…
15

16. 16

17. 200 OK
{
"success": false,
"error": {
"code": 666,
"message": "because fk u thats why"
}
17

18. 400 Bad Request
401 Unauthorized
404 Not Found
402 Payment Required
409 Conflict
…
18

19. 418 I’m a teapot
19

22. Forbidden
Authorization: Bearer ToKeN
@wice_

23. /users
/orders
/profile
…
GET
POST
PUT
DELETE
OPTIONS
HEAD
PATCH
…
200
201
…
300
301
…
400
401
…
500
501
…
покроет все ваши кейсы
23

24. REST уровень 3
24

25. Гипертекст
25

26. HATEOAS
Hypermedia As The Engine Of Application State
26

27. представление ресурса = данные + контролы
27

28. GET /feed
200 OK
{
"data": [
{
"title": "...",
"links": {
"details": "http://..."
}
},
....
],
"links": {
"self": "http://...",
"first": "http://...",
"prev": "http://...",
"next": "http://...",
"last": "http://..."
}
}
28

29. GET /feed?min_id=100500
200 OK
{
"data": [
{
"title": "...",
"links": {
"details": “http://..."
}
},
....
],
"links": {
"self": "http://...",
"first": "http://...",
"prev": "http://...",
"next": "http://...",
"last": "http://..."
}
}
29

30. GET /films/themartian
200 OK
{
"data": {
"title": "Марсианин",
"description": "Как Мэт Дэймон выращивал картошку на Марсе",
"duration": 140,
"poster": "https://s3.amazon.com/buckets/23aGd23asdsf.png"
},
"links": {
"self": “http://.../themartian”,
"booking": “http://.../themartian/bookings"
}
}
30

31. GET /films/themartian
200 OK
{
"data": {
"title": "Марсианин",
"description": "Как Мэт Дэймон выращивал картошку на Марсе",
"duration": 140,
"poster": "https://s3.amazon.com/buckets/23aGd23asdsf.png"
},
"links": {
"self": “http://.../themartian”,
"booking": “http://.../themartian/bookings"
}
}
OPTIONS /films/themartian/bookings
204 No Content
Allow: HEAD,GET,POST,OPTIONS
31

32. POST /films/themartian/bookings
{
count: 3
}
201 Created
Location: http://..../bookings/1
32

33. GET /films/themartian/bookings/1
200 OK
{
"data": {
"count": 3,
"date": "Tue Nov 03 2015 21:45:55 GMT+0200 (EET)",
"status": "waiting"
},
"links": {
"self": "http://..../bookings/1",
"cancel": "http://..../bookings/1/cancel",
"pay": "http://.../bookings/1/pay"
}
}
33

34. Стейт-машина
Переходим в новые состояния по ссылке
34

35. Некоторые приёмы
• Безопасные и идемпотентные операции
• Кеширование неизменяемых ресурсов
• X- заголовки
• Вендорные типы данных (
application/vnd.myapi.basket.v1+json
)
35

36. В чём профит?
36

37. Делаем клиент тоньше, не
нужно больше хачить URL

38. Распределённые приложения

39. API могут использовать роботы

40. Самодокументирование

41. Developer Experience

42. Вопросы к HATEOAS
42

43. В JSON нет ссылок и форм.
Есть спецификации:
HAL, Siren, json:api
43

44. Нужна ли теперь
документация?
Нужна. REST для машин.
44

45. Слишком академично или
много лишнего.
Не нужно реализовывать
спецификации в полном
объёме.
45

46. А Twitter, Facebook, … не
применяют HATEOAS.
Run-time vs Design-time
46

47. Почитать
• https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm
• http://roy.gbiv.com/untangled/2008/rest-apis-must-be-
hypertext-driven
• http://martinfowler.com/articles/richardsonMaturityModel.html
• REST in Practice by Jim Webber, Savas Parastatidis, and Ian
Robinson
• http://www.jeffknupp.com/blog/2014/06/03/why-i-hate-hateoas
• http://timelessrepo.com/haters-gonna-hateoas

48. Спасибо, задавайте
вопросы!
48