Talk by Sam Rottenberg, Technical Lead at FABERNOVEL TECHNOLOGIES

1. How HATEOAS
changes the way to
build and test the APIs
Sam ROTTENBERG
API Days, Paris, 30th January 2018

2. 2//
Hate oh what?

3. 3//
HATEOAS
Hypermedia As the Engine Of Application State
“REST is defined by four interface constraints:
- identification of resources;
- manipulation of resources through representations;
- Selfdescriptive messages;
- and, hypermedia as the engine of application state.”
[Fielding 2000]

4. 4//
Example of web
application

5. 5//
Example of web application
PAAS Web Application
- List apps
- App details page
- App management operations
- Start / Stop
- Delete
- ...

6. 6//
Levels of REST
Richardson
Maturity Model

7. 7//
Levels of REST / Richardson Maturity Model
Level 0
- HTTP as the communication protocol
- Service↔URI
- Call semantics contained in custom messages
- POST requests
- Always 200 status code (even for errors)
- SOAP-like (without envelope)

8. 8//
Levels of REST / Richardson Maturity Model
Level 0 - Example
- POST /appService
- Request body
- <startAppRequest>...</startAppRequest>
- Response body (status code 200)
- <startAppResponse>...</startAppResponse>
- <startAppError>...</startAppError>

9. 9//
Levels of REST / Richardson Maturity Model
Level 1
- Resources
- Resource↔URI
- Calling “methods” on resources (object oriented style)
- Call semantics (cf. level 0)

10. 10//
Levels of REST / Richardson Maturity Model
Level 1 - Example
- POST /apps/my-app
- Request body
- <startAppRequest>...</startAppRequest>
- Response body (status code 200)
- <startAppResponse>...</startAppResponse>
- <startAppError>...</startAppError>

11. 11//
Levels of REST / Richardson Maturity Model
Level 2
- HTTP Verbs + HTTP Response codes
- Resource↔URI
- Function↔Verb + URI
- Comply with HTTP verbs and response codes semantics
- GET : safe, does not change state
- POST/PUT/DELETE : changes state
- 200, 201, 401, 402, etc.

12. 12//
Levels of REST / Richardson Maturity Model
Level 2 - Example
- GET /apps/my-app
- 200 Ok with app details in body
- PUT /apps/my-app
- 204 No Content
- DELETE /apps/my-app
- 204 No Content
- POST /apps
- 201 Created

13. 13//
Levels of REST / Richardson Maturity Model
Level 3
- Enriched resources representations in responses with
hypermedia controls
- Links to resources or actions related to the current
resource
- Forms
- Datatype information (links to schemas)
- ...

14. 14//
Levels of REST / Richardson Maturity Model
Level 3 - Example
<app id=”my-app”>
<link rel=”stop” uri=”/apps/my-app/stop” />
...
</app>

15. 15//
Immediate
advantage of
HATEOAS

16. 16//
Immediate advantage of HATEOAS
Server knows best
- Business rules
- Actions depending on access rights
- Actions depending on resource state
- Level 2 and below
- Duplicated rules client-side
- Level 3 - HATEOAS
- Navigation based on server’s response

17. 17//
Going further with
HATEOAS

18. 18//
Going further with HATEOAS
I have a dream
- Auto-generated static and dynamic API documentation
- Scaffolding based on the API documentation
- API demo
- Testing
- Adding semantics (with shared ontologies)
- Auto-discovery of services
- Client-side development becomes building UI kits for
pre-defined semantics

19. 19//
So why isn’t
HATEOAS
everywhere?!

20. 20//
HATEOAS Challenges
The dark side of the moon
- Building HATEOAS API is very difficult
- Frameworks are function-oriented and not
resource-oriented
- Too much workload to maintain documentation by
hand
- Various formats (HAL, JSON-LD, Hydra, etc.), no
standard
- Need specific tools/framework

21. 21//
HATEOAS needs
your help!

22. 22//
Thanks!
Questions?