Hypermedia API (MinskJS version)

Transcript

1. Hypermedia API 1
2. Артём Бей @defly_self Fullstack dev в Trinity Mirror 2
4. Representational State Transfer “Architectural Styles and the Design of Network-based Software Architectures” Roy Fielding 4
5. REST это архитектурный стиль для распределенных гипермедиа систем. 5
6. REST != HTTP 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": "not valid req" } } /users POST /users/1 {…} POST /orders {…} /users/1 /orders 11
12. REST уровня 2 12
13. REST уровня 2 Используем HTTP по спецификации 13
14. GET POST PUT DELETE OPTIONS HEAD PATCH … 14
16. 200 OK { "success": false, "error": { "code": 666, "message": "because fk u thats why" } 16
17. 400 Bad Request 401 Unauthorized 403 Forbidden 404 Not Found 402 Payment Required 409 Conflict … 17
18. 418 I’m a teapot P.S. Больше статусов на: http://httpstatusdogs.com/ https://http.cat/ 18
19. /users /orders /profile … GET POST PUT DELETE OPTIONS HEAD PATCH … 200 201 … 300 301 … 400 401 … 500 501 … покроют все ваши кейсы 19
20. REST уровень 3 20
21. Гипертекст 21
22. HATEOAS Hypermedia As The Engine Of Application State 22
23. представление ресурса = данные + контролы 23
24. GET /feed 200 OK { "data": [ { "title": "...", "links": { "details": "http://..." } }, .... ], "links": { "self": "http://...", "first": "http://...", "prev": "http://...", "next": "http://...", "last": "http://..." } } 24 << < > >>
25. GET /feed?min_id=100500 200 OK { "data": [ { "title": "...", "links": { "details": “http://..." } }, .... ], "links": { "self": "http://...", "first": "http://...", "prev": "http://...", "next": "http://...", "last": "http://..." } } 25 << < > >>
26. 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" } } 26
27. OPTIONS /films/themartian/bookings 204 No Content Allow: HEAD,GET,POST,OPTIONS 27 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" } }
28. POST /films/themartian/bookings { count: 3 } 201 Created Location: http://..../bookings/1 28
29. 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" } } 29
30. Стейт-машина Переходим в новые состояния по ссылке 30
31. Состояние вычисляется в одном месте
32. Забываем о формировании URL на клиенте
33. Распределённые приложения "links": { "self": "http://...", "upload": "http://...s3.amazonaws.com/", "pay": "https://api.stripe.com/v1/charges/", "convert": "https://...docx2pdf.mcrsrvs.com/" }
34. Discoverability
35. Developer Experience
36. Некоторые приёмы • Безопасные и идемпотентные операции • Кеширование неизменяемых ресурсов • X- заголовки • Вендорные типы данных (application/ vnd.myapi.basket.v1+json) 36
37. Вопросы к HATEOAS 37
38. В JSON нет ссылок и форм Есть спецификации: HAL, Siren, json:api 38
39. Нужна ли теперь документация? Нужна. REST для машин. 39
40. Слишком академично или много лишнего Не нужно реализовывать спецификации в полном объёме 40
41. Почитать • 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 • http://www.jeffknupp.com/blog/2014/06/03/why-i-hate- hateoas • http://timelessrepo.com/haters-gonna-hateoas
42. Спасибо, задавайте вопросы! 42