RESTful API documentation and hypermedia
📑 Chapter summary
In this chapter, the students must document their RESTful API. The minimum requirements are summarized in the Minimum Requirements section of the Project Work Assignment. Note that if you do not meet Minimum Requirements this section wont be evaluated.- Understand connectedness and/or hypermedia
- Write API documentation
You have two options:
- Implement the API using a non-hypermedia format (RESTful CRUD). In this case, it is recommended that all your resources are connected (linking to other resources). Anyhow, you cannot get full points in this section if you do not design your API using an hypermedia format
- Using an hypermedia format. Lots of examples provided in Exercise 3. You can get full points. In this case you need to clearly include in the documentation a profile with link relations and semantic descriptors.
✔️ Chapter evaluation (max 15 points)
You can get a maximum of 15 points after completing this section. More detailed evaluation is provided in the evaluation sheet in Lovelace.📑 Content that must be included in the section
Include a state diagram of your application, with all the application states. Each resource must be an application state. Describe also the state transitions. To build this diagram you should reuse the diagram created in DL1. You can use online tools such as draw.io or lucidchart to create the diagrams. You have an example in the following image
📑 Content that must be included in the section
Use any of the tools presented in Exercise 3 to document the API.
For all resources you must cover:
- The possible HTTP methods exposed by this resource
- The headers in the request and responses
- The media type utilized (in the response Content-Type header). If you are utilizing your own media-type you must describe it in the section Own media type implementation.
- The format of the HTTP request body (just for PUT/POST), providing a clear example. If necessary, comment the example.
- The format of the HTTP response body, providing a clear example. If necessary, comment the example.
- The error conditions, status code and format of the error response, providing a clear example.
-
If you are using an hypermedia type you must provide the profile utilized, including:
- Link relations. Include methods and format of the requests if they are defined in the media type. Use as much as possible IANA defined relations.
- Semantic descriptors. If you utilize a descriptor used in some other profile (e.g. schema.org) provide the link.
- If you are extending other profiles, do not forget to link to the extended profile.
The API documentation is available on swagger-ui at location http://127.0.0.1:8000/swagger-ui, when running main.py.
📑 Content that must be included in this section. Fill this section if your API uses hypermedia
Declare your chosen mediatype, and provide your reasoning for choosing that mediatype. For each custom link relation defined in your API's namespace, explain why it was needed (i.e. why there wasn't a suitable relation in the IANA standard). Explain how Connectedness is achieved in your API.We chose Mason for hypermedia. It was chosen because of the course exercises.
Hypermedia Implementation Documentation
Justification on Hypermedia Implementation
Our API leverages hypermedia as a means to enhance the discoverability, flexibility, and navigability of resources. Hypermedia-driven APIs enable clients to dynamically interact with resources by following links provided in API responses. This approach promotes loose coupling between clients and the server, allowing for easier evolution of the API over time.
Chosen Media Type:
We have opted for the Mason media type for implementing hypermedia in our API. Mason is a hypermedia type that extends JSON with conventions for linking resources and actions. We chose Mason due to its simplicity, readability, and compatibility with JSON-based APIs. By using Mason, we can provide clients with structured metadata, including links to related resources and controls for performing actions.
Custom Link Relations:
mumeta:delete-product-listing: Reasoning: We have defined this custom link relation to indicate the action of deleting a product listing resource. While the IANA standard provides generic link relations, there isn't a specific relation for deleting resources. Therefore, we introduced this custom relation to explicitly convey the delete action, enhancing the clarity and specificity of API interactions. Achieving Connectedness:
Connectedness in our API is achieved through the inclusion of hypermedia controls (links) in API responses. Each resource representation includes links to related resources and actions, enabling clients to navigate through the API dynamically. By following these links, clients can discover and interact with other resources without prior knowledge of their URIs or specific endpoints. This hypermedia-driven approach fosters a more intuitive and adaptable API experience, facilitating seamless client-server communication.
Example Implementation:
{
"id": "12345",
"name": "Product A",
"price": 100.00,
"description": "Lorem ipsum dolor sit amet.",
"_links": {
"self": { "href": "/products/12345" },
"edit": { "href": "/products/12345", "method": "PUT" },
"delete": { "href": "/products/12345", "method": "DELETE" }
}
}
In the example above, a product resource representation includes links (_links) to itself, allowing clients to retrieve, update, or delete the product. These links provide clients with actionable controls, enabling them to interact with the API in a meaningful and intuitive manner.
| Task | Student | Estimated time |
|---|---|---|
| API Documentation | Kurosh Husseini | 3 |
| API Documentation | Bishwas Wagle | 3 |
| API Documentation | Konsta Laurila | 3 |
| API Documentation | Aleksi Illikainen | 3 |