APIDays 2018 - APIOps & Microservices - How HATEOAS changes the way to build and test the APIs
1 like273 views
This document discusses how implementing HATEOAS (Hypermedia as the Engine of Application State) changes the way APIs are built and tested. It describes the Richardson maturity model for REST APIs, which progresses from simple HTTP as a communication protocol (Level 0) to fully utilizing hypermedia links and controls in responses to drive the application state (Level 3). Implementing HATEOAS at Level 3 has the immediate advantage that the server dictates valid actions and navigation rather than duplicating these rules on the client. The document envisions auto-generated documentation, scaffolding, testing and discovery if HATEOAS is fully embraced, but notes it is difficult to implement and challenges include a lack of frameworks, standards and tools.
![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]](https://image.slidesharecdn.com/apidays-hateoas2-180206132037/85/APIDays-2018-APIOps-Microservices-How-HATEOAS-changes-the-way-to-build-and-test-the-APIs-3-320.jpg)
APIDays 2018 - APIOps & Microservices - How HATEOAS changes the way to build and test the APIs
- 1. How HATEOAS changes the way to build and test the APIs Sam ROTTENBERG API Days, Paris, 30th January 2018
- 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]
- 5. 5// Example of web application PAAS Web Application - List apps - App details page - App management operations - Start / Stop - Delete - ...
- 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>
- 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
- 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
- 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