The Swamp of Plain Old XML
POST /
Client Server
createBook
…
Slide 5
Slide 5 text
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"
}
}
Slide 6
Slide 6 text
HTTP Verbs
Client Server
POST /books
PUT /books/42
{"title": "Hitchhiker's Guide to The Galaxy"}
{"title": "Hitchhiker's Guide to The Galaxy"}
Slide 7
Slide 7 text
Hypermedia
Slide 8
Slide 8 text
Links and Relations
{
"_links" :{
"list": {
"href": "/books"
}
// more links ...
}
}
GET /
Slide 9
Slide 9 text
Links and Relations
{
"bookList": [{
"title": "...",
"_links": {
"self": {
"href": "/books/42"
}
}
}
}
GET /books
Slide 10
Slide 10 text
Links and Relations
Slide 11
Slide 11 text
@SpringBootApplication
@EnableHypermediaSupport(type = HypermediaType.HAL)
public class MyApplication{
public static void main(String[] args) {
SpringApplication.run(MyApplication.class, args);
}
}
Hypermedia with Spring Boot
Slide 12
Slide 12 text
@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
Slide 13
Slide 13 text
Hypermedia?
Slide 14
Slide 14 text
No content
Slide 15
Slide 15 text
Good API Docs
Slide 16
Slide 16 text
No content
Slide 17
Slide 17 text
No content
Slide 18
Slide 18 text
No content
Slide 19
Slide 19 text
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.")));
Slide 20
Slide 20 text
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.")));
POST /orders
PUT /orders/4711
PUT /orders/4711
Fat Resource
{
"orderId": 4711,
"orderItems": [
{
"articleId": 0815,
...
}
]
}
Slide 26
Slide 26 text
{
"orderId": 4711,
"orderItems": [
{
"articleId": 0815,
...
}
]
}
POST /orders
POST /orders/4711/items
PUT /orders/4711/items
Nested Resource
DELETE /orders/4711/items
Slide 27
Slide 27 text
{
"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
Slide 28
Slide 28 text
No content
Slide 29
Slide 29 text
No content
Slide 30
Slide 30 text
{
"orderId": 4711,
"status": "COMPLETE" ,
"orderItems": [
{
"articleId": 0815,
...
}
]
}
PUT /orders/4711
State Change
Slide 31
Slide 31 text
// no content
POST /orders/4711/complete
Resource Action
Slide 32
Slide 32 text
{
"orderId": 4711,
...
}
POST /orderCompletions
Action Resource
GET /orderCompletions
Slide 33
Slide 33 text
No content
Slide 34
Slide 34 text
No content
Slide 35
Slide 35 text
Testing an API
Slide 36
Slide 36 text
Integration Testing a REST API
Slide 37
Slide 37 text
Testing Endpoints on the Provider Side
GET /orders/4711
POST /orders
DELETE /orders/4711
Slide 38
Slide 38 text
Testing Interactions
Slide 39
Slide 39 text
No content
Slide 40
Slide 40 text
No content
Slide 41
Slide 41 text
Adding an Identifier
Slide 42
Slide 42 text
Removing an Identifier
Slide 43
Slide 43 text
Changing Semantics of an Identifier
Slide 44
Slide 44 text
GET /orders
GET /v1/orders
GET /v2/orders
Content-Type: application/json
Content-Type: application/json
Content-Type: application/json
URI Versioning
Slide 45
Slide 45 text
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
Slide 46
Slide 46 text
No content
Slide 47
Slide 47 text
No content
Slide 48
Slide 48 text
No content
Slide 49
Slide 49 text
OAuth 2.0
Slide 50
Slide 50 text
OAuth 2.0
Slide 51
Slide 51 text
JWT
create signedtoken
Client Server
login withusername/ password
returntoken
send token witheach request
check token signature
read user informationfromtoken
returnresponse