Best of REST (JAX 2018)

A tour through some of the major decisions we have to make when implementing a HTTP API (or even a REST API).

Transcript

1. @TomHombergs Best of REST
4. The Swamp of Plain Old XML POST / Client Server <?xml version="1.0"?> <request> <action>createBook</action> <payload> <title>…</title> </payload> </request>
5. Resources Client Server POST /books POST /books/42?action=update {"title": "Hitchhiker's Guide to The Galaxy"} { "action": "create", "payload": { "title": "Hitchhiker's Guide to The Galaxy" } }
6. HTTP Verbs Client Server POST /books PUT /books/42 {"title": "Hitchhiker's Guide to The Galaxy"} {"title": "Hitchhiker's Guide to The Galaxy"}
7. Hypermedia
8. Links and Relations { "_links" :{ "list": { "href": "/books" } // more links ... } } GET /
9. Links and Relations { "bookList": [{ "title": "...", "_links": { "self": { "href": "/books/42" } } } } GET /books
10. Links and Relations
11. @SpringBootApplication @EnableHypermediaSupport(type = HypermediaType.HAL) public class MyApplication{ public static void main(String[] args) { SpringApplication.run(MyApplication.class, args); } } Hypermedia with Spring Boot
12. @GetMapping(path = "books/{id}") public ResponseEntity getBook(@PathVariable Long id) { Book book = bookRepository.findOne(id); BookResource result = bookAssembler.toResource(book); return new ResponseEntity(result, HttpStatus.OK); } Hypermedia with Spring Boot
13. Hypermedia?
15. Good API Docs
19. Generating Docs with Spring Rest Docs document("books/create", links(halLinks(), linkWithRel("self") .description("Link to the created book."), requestFields( fields.withPath("title") .description("The title of the book.")));
20. Generating Docs with Spring Rest Docs document("books/create", links(halLinks(), linkWithRel("self") .description("Link to the created book."), requestFields( fields.withPath("title") .description("The title of the book.")));
21. @Test public void createProjectSuccessfully() throws Exception { ProjectResource project = projectResource().validProjectResource(); mvc().perform(post("/books") .content(toJsonWithoutLinks(project)) .contentType(MediaType.APPLICATION_JSON)) .andExpect(status().isCreated()) .andExpect(containsResource(ProjectResource.class)) .andDo(document(...)); } Generating Docs from Tests
22. Generating Docs from Tests
23. Contract First or Code First?
25. POST /orders PUT /orders/4711 PUT /orders/4711 Fat Resource { "orderId": 4711, "orderItems": [ { "articleId": 0815, ... } ] }
26. { "orderId": 4711, "orderItems": [ { "articleId": 0815, ... } ] } POST /orders POST /orders/4711/items PUT /orders/4711/items Nested Resource DELETE /orders/4711/items
27. { "orderId": 4711, "orderItemCount": 2 } GET /orders/4711?view=summary Resource Views GET /orders/4711/view/summary GET /orders/4711 Accepts: application/vnd+adesso.orderSummary+json
30. { "orderId": 4711, "status": "COMPLETE" , "orderItems": [ { "articleId": 0815, ... } ] } PUT /orders/4711 State Change
31. // no content POST /orders/4711/complete Resource Action
32. { "orderId": 4711, ... } POST /orderCompletions Action Resource GET /orderCompletions
35. Testing an API
36. Integration Testing a REST API
37. Testing Endpoints on the Provider Side GET /orders/4711 POST /orders DELETE /orders/4711
38. Testing Interactions
41. Adding an Identifier
42. Removing an Identifier
43. Changing Semantics of an Identifier
44. GET /orders GET /v1/orders GET /v2/orders Content-Type: application/json Content-Type: application/json Content-Type: application/json URI Versioning
45. GET /orders Accept: application/vnd+adesso.orders+json Header Versioning GET /orders Accept: application/vnd+adesso.orders+json;v=1 GET /orders Accept: application/vnd+adesso.orders+json;v=2
49. OAuth 2.0
50. OAuth 2.0
51. JWT create signedtoken Client Server login withusername/ password returntoken send token witheach request check token signature read user informationfromtoken returnresponse
52. JWT