RESTful API documentation and hypermedia - tharindu326/PWP GitHub Wiki
📑 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.
✏️ Access Control API documentation
📑 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.✏️
Mason hypermedia format was selected whcih is a JSON-based media type designed to turn REST APIs into hypermedia based APIs, enabling them to include controls (such as links and actions) directly in API responses. The reasons for selecting Mson;
- Mason allows each API response to explain itself. It adds clear meanings to the data returned, so the response not only contains the information but also tells you what it means and what you can do with it.
- Mason allows for rich error responses, which can include both human and machine-readable information.
- With Mason, API responses can include controls, such as links and forms, which inform the client of possible interactions with the API.
The custom link relations in the API are there because they match the specific tasks that this API needs to perform, which the more standard IANA link relation types don't fully address. They're like special commands that help users navigate and interact with the API's unique features, particularly for managing user identities and their access rights.
| Resource | Link Relations | Description (why link relation) |
|---|---|---|
| Permissions | permissions | Represents the list or collection of all permissions. |
| permission-by | Points to the permission applicable to a specific identity. | |
| Identities | edit | Allows editing details of a specific identity. |
| delete | Permits the deletion of a specific identity. | |
| get-by-id | Retrieves the details of an identity using its unique ID. | |
| get-by-name | Fetches an identity's details using its name. | |
| put | Endpoint to register a new identity. | |
| access-requests | Indicates the access requests initiated by or related to the identity. | |
| Access-logs | get | Used to retrieve all access logs. |
| log-by | Refers to access logs that originated from a particular identity. | |
| by-access | Relates to the identity that has been logged by a particular access log entry. | |
| Access-requests | request-access | Submits a new access request for an identity. |
| get | Retrieves all access requests or details about a specific access request. | |
| access-by | Denotes the identity associated with a specific access request. |
Connectedness in this API is achieved by using hypermedia controls in the responses, which enable clients to navigate the API dynamically. Each response contains the relevant links and actions that a client can perform next, depending on the current state and context. This makes the API discoverable and navigable, adhering to HATEOAS principles.
| Task | Student | Estimated time |
|---|---|---|
| implemention of hypermedia | Tharindu Muthukuda Walawwe ([email protected]) | 4h |
| prpearing the Swagger documentation and evaluate it with swagger editor | Tharindu Muthukuda Walawwe ([email protected]) | 2h |
| implmemtation of MASON and intergrate it with APIs | Tharindu Muthukuda Walawwe ([email protected]) | 2h |
| documnetation of link relations and digrams | Tharindu Muthukuda Walawwe ([email protected]) | 3h |
| pytests update after hypermedia intergration | Tharindu Muthukuda Walawwe ([email protected]) | 4h |