building awesome api with spring
TRANSCRIPT
2015Vladimir Tsukur
Building AWESOME API
with
REST
2
Vladimir Tsukur
partner @
engineer @
engineer / architect @
flushdia vtsukur
3
Web API? Why Should I Care?
Idea! Currency Black Market!
5
finance.i.ua - Listing
6
finance.i.ua - Ad Creation
7
8
Spring Boot
Tools
Spring Data
Spring Data REST
CODING TIME !
10
CRUD Style API
Method URL Task
POST /ads Create ad
GET /ads View ads
GET /ads/{id} Get ad
PATCH /ads/{id} Update ad
DELETE /ads/{id} Delete ad
11
I am sorry, but we have business process
12
if (status == Status.NEW) { publishedAt = LocalDateTime.now(); status = Status.PUBLISHED;} …
CRUD is NOT enough
if (status == Status.NEW) { publishedAt = LocalDateTime.now(); status = Status.PUBLISHED;} …
13
API Changes
Method URL Task
POST /ads/{id}/publishing Publish ad
POST /ads/{id}/expiration Expire ad
GET /ads/search/published Get published ads
CODING TIME !
/uri Style Adoption?
43%
16
17
URI Binding & Construction
Task Method URL
Update ad PATCH /ads/{id}
Delete ad DELETE /ads/{id}
Publish ad POST /ads/{id}/publishing
Expire ad POST /ads/{id}/expiration
18
"Figuring" Out the Flow
Task Method URLUpdate ad
(only if NEW) PATCH /ads/{id}
Delete ad (only if NEW) DELETE /ads/{id}
Publish ad (only if NEW) POST /ads/{id}/
publishingExpire ad
(only if PUBLISHED)
POST /ads/{id}/expiration
Should work on my iPhone 6s!
20
21
Hypermedia =
{ "amount": 3000, "currency": "USD", …}
data
{ … "_links": { "publishing": { "href": "/ads/1/publishing" }, "update": { "href": "/ads/1" }, "deletion": { "href": "/ads/1" }, … }}
links
+
22
Hypermedia API
Link Relation
Task Method
update Update ad PATCH
deletion Delete ad DELETE
publishing Publish ad POST
expiration Expire ad POST
23
Tools
Spring HATEOAS
CODING TIME !
25
HAL = Hypertext Application Language
"I want hypermedia!"
40%
27
28
Siren Actions "actions": [ { "name": "create-ad", "method": "POST", "href": "/ads", "type": "application/json", "fields": [ { "name": "type", "type": "radio" }, { "name": "quantity", "type": "number" }, { "name": "currency", "type": "radio" }, … ] } ]
I want a convenient browser for
HAL … ASAP!
SHOW TIME !
We are ready to go to prod,
right ;)?
32
No, we are not!
1. Data View Customization 2. Validation 3. Application Events 4. Caching / Version Control 5. Security 6. Export Control 7. …
33
Getting awesome!
1. Data View Customization 2. Validation 3. Application Events 4. Caching / Version Control 5. Security 6. Export Control 7. …
34
Integration Domain Model
{ "id": 345, "type": "SELL", "amount": 3000, "currency": "USD", "rate": 25.25, "location": { "city": "Одесса", "area": "Приморский" }, "comment": "быстрее детка!", "publishedAt": "…07:52:22…", "status": "PUBLISHED", …}
{ "type": "SELL", "amount": 3000, "currency": "USD", "rate": 25.25, "phoneNumber": "+380…" …}
CODING TIME !
36
Getting awesome!
1. Data View Customization 2. Validation 3. Application Events 4. Caching / Version Control 5. Security 6. Export Control 7. …
CODING TIME !
SECURITY
CODING TIME !
Testing? Documentation?
41
SHOW TIME !
44
Outcomes - API
1. Use links for state transitions 2. Separate integration domain
from the core domain 3. Expose only the necessary parts 4. Leverage caching 5. Combine testing with
documentation 6. Do NOT document URLs!
45
Outcomes -
1. Spring Data REST - simple, CRUD-y and HATEOAS-y; extensible
PRO TIP: won't solve everything 2. Spring MVC - always there to help 3. Link stuff with Spring HATEOAS 4. Spring Security to the rescue
when you need to protect API 5. Document with Spring REST Docs
46
Thanks! Questions?
https://github.com/vtsukur/spring-rest-black-market
47
Thanks! Questions?
48
References1. http://www.google.com.ua/trends/explore#q=web%20api%2C%20rest%20api&cmpt=q&tz= 2. http://finance.i.ua/market/ 3. http://projects.spring.io/spring-boot/ 4. http://projects.spring.io/spring-data/ 5. http://docs.spring.io/spring-data/jpa/docs/1.7.2.RELEASE/reference/html/ 6. http://projects.spring.io/spring-data-rest/ 7. http://docs.spring.io/spring-data/rest/docs/2.3.0.RELEASE/reference/html/ 8. https://spring.io/blog/2014/07/14/spring-data-rest-now-comes-with-alps-metadata 9. http://projects.spring.io/spring-hateoas/ 10. http://docs.spring.io/spring-hateoas/docs/0.17.0.RELEASE/reference/html/ 11. https://github.com/spring-projects/spring-restdocs 12. https://blog.akana.com/hypermedia-apis 13. http://www.apiacademy.co/lessons/api-design/web-api-architectural-styles 14. http://www.programmableweb.com/news/modern-api-architectural-styles-offer-developers-choices/2014/06/13 15. https://en.wikipedia.org/wiki/Hypermedia 16. http://stateless.co/hal_specification.html 17. https://github.com/kevinswiber/siren 18. https://www.mnot.net/blog/2013/06/23/linking_apis 19. http://oredev.org/2010/sessions/hypermedia-apis 20. http://vimeo.com/75106815 21. https://www.innoq.com/blog/st/2012/06/hypermedia-benefits-for-m2m-communication/ 22. http://ws-rest.org/2014/sites/default/files/wsrest2014_submission_12.pdf 23. http://www.infoq.com/news/2014/03/ca-api-survey 24. https://twitter.com/hypermediaapis 25. https://www.youtube.com/watch?v=hdSrT4yjS1g 26. https://www.youtube.com/watch?v=mZ8_QgJ5mbs 27. http://nordsc.com/ext/classification_of_http_based_apis.html 28. http://soabits.blogspot.no/2013/12/selling-benefits-of-hypermedia.html 29. https://github.com/mamund/Building-Hypermedia-APIs 30. http://tech.blog.box.com/2013/04/get-developer-hugs-with-rich-error-handling-in-your-api/
49
Images1. http://www.google.com.ua/trends/explore#q=web%20api%2C%20rest%20api&cmpt=q&tz= 2. http://finance.i.ua/market/ 3. http://projects.spring.io/spring-boot/ 4. http://projects.spring.io/spring-data/ 5. http://docs.spring.io/spring-data/jpa/docs/1.7.2.RELEASE/reference/html/ 6. http://projects.spring.io/spring-data-rest/ 7. http://docs.spring.io/spring-data/rest/docs/2.3.0.RELEASE/reference/html/ 8. https://spring.io/blog/2014/07/14/spring-data-rest-now-comes-with-alps-metadata 9. http://projects.spring.io/spring-hateoas/ 10. http://docs.spring.io/spring-hateoas/docs/0.17.0.RELEASE/reference/html/ 11. https://github.com/spring-projects/spring-restdocs 12. https://blog.akana.com/hypermedia-apis 13. http://www.apiacademy.co/lessons/api-design/web-api-architectural-styles 14. http://www.programmableweb.com/news/modern-api-architectural-styles-offer-developers-choices/2014/06/13 15. https://en.wikipedia.org/wiki/Hypermedia 16. http://stateless.co/hal_specification.html 17. https://github.com/kevinswiber/siren 18. https://www.mnot.net/blog/2013/06/23/linking_apis 19. http://oredev.org/2010/sessions/hypermedia-apis 20. http://vimeo.com/75106815 21. https://www.innoq.com/blog/st/2012/06/hypermedia-benefits-for-m2m-communication/ 22. http://ws-rest.org/2014/sites/default/files/wsrest2014_submission_12.pdf 23. http://www.infoq.com/news/2014/03/ca-api-survey 24. https://twitter.com/hypermediaapis 25. https://www.youtube.com/watch?v=hdSrT4yjS1g 26. https://www.youtube.com/watch?v=mZ8_QgJ5mbs 27. http://nordsc.com/ext/classification_of_http_based_apis.html 28. http://soabits.blogspot.no/2013/12/selling-benefits-of-hypermedia.html 29. https://github.com/mamund/Building-Hypermedia-APIs 30. http://tech.blog.box.com/2013/04/get-developer-hugs-with-rich-error-handling-in-your-api/ 31. http://img.112.ua/original/2015/01/16/114777.jpg 32. http://eimg.pravda.com/images/doc/6/7/6700cff-hontareva.jpg 33. http://imgcdn1.luxnet.ua/tv24/resources/newsfiles/201502/121.jpg 34. http://beta2.odessa-daily.com.ua/uploads/imgsc/
84d27d3a6af024c32b16c54216e01777d50c625d_b_fa55cd70c403167a5277a6db96eb8c7c2b6139d4.jpg