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