Typical way to design and expose HTTP API today is a so called CRUD approach: come up with URL templates for resources, map create-read-update-delete operations to HTTP verbs and serialize domain model as JSON. This approach is nice and easy, but has its limitations. During this presentation we'll create an application enhancing its primitive CRUD API all the way to modern, business-centric hypermedia style API using a set of tools from Spring, namely Spring Boot, Spring Data REST, Spring HATEOAS and Spring REST Docs!

1. 2015Vladimir Tsukur
Building
AWESOME API
with

2. REST
2
Vladimir Tsukur
partner @
engineer @
engineer /
architect @
flushdia vtsukur

3. 3
Web API? Why Should I Care?

4. Idea! Currency
Black Market!

5. 5
finance.i.ua - Listing

6. 6
finance.i.ua - Ad Creation

7. 7

8. 8
Spring Boot
Tools
Spring Data
Spring Data REST

9. CODING TIME !

10. 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. 11
I am
sorry, but we have
business process

12. 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. 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

14. CODING TIME !

15. /uri Style Adoption?
43%

16. 16

17. 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. 18
"Figuring" Out the Flow
Task Method URL
Update ad
(only if NEW) PATCH /ads/{id}
Delete ad
(only if NEW) DELETE /ads/{id}
Publish ad
(only if NEW) POST
/ads/{id}/
publishing
Expire ad
(only if
PUBLISHED)
POST
/ads/{id}/
expiration

19. Should work on my
iPhone 6s!

20. 20

21. 21
Hypermedia =
{
"amount": 3000,
"currency": "USD",
…
}
data
{
…
"_links": {
"publishing": {
"href": "/ads/1/publishing"
},
"update": {
"href": "/ads/1"
},
"deletion": {
"href": "/ads/1"
},
…
}
}
links
+

22. 22
Hypermedia API
Link
Relation
Task Method
update Update ad PATCH
deletion Delete ad DELETE
publishing Publish ad POST
expiration Expire ad POST

23. 23
Tools
Spring HATEOAS

24. CODING TIME !

25. 25
HAL = Hypertext Application
Language

26. "I want hypermedia!"
40%

27. 27

28. 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" },
…
]
}
]

29. I want a
convenient
browser for
HAL …
ASAP!

30. SHOW TIME !

31. We are ready
to go to prod,
right ;)?

32. 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. 33
Getting awesome!
1. Data View Customization
2. Validation
3. Application Events
4. Caching / Version Control
5. Security
6. Export Control
7. …

34. 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…"
…
}

35. CODING TIME !

36. 36
Getting awesome!
1. Data View Customization
2. Validation
3. Application Events
4. Caching / Version Control
5. Security
6. Export Control
7. …

37. CODING TIME !

38. SECURITY

39. CODING TIME !

40. Testing?
Documentation?

41. 41

42. SHOW TIME !

44. 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. 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. 46
Thanks!
Questions?
https://github.com/vtsukur/spring-rest-black-market

47. 47
Thanks!
Questions?

48. 48
References
1. 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. 49
Images
1. 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