Repository navigation
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✏️ Draw here your state machine diagram
The states of this API implementation is shown in the above.
Start: This is the initial state of the state machine where the API interaction begins.
Recipient List: This state represents the resource for managing the list of recipients. It supports two actions:
Recipient Item: This state represents a specific recipient item within the recipient list. It supports three actions:
Template List: This state represents the resource for managing the list of email templates. It supports two actions:
Template Item: This state represents a specific email template item within the template list. It supports three actions:
Notification: This state represents the action of sending an email notification to subscribed recipients using a specified template. It supports the POST action.
Email Audit List: This state represents the resource for accessing email audit information. It supports two actions:
These states and their transitions form a flow that allows for managing recipients and email templates, sending notifications, and accessing email audit information within the email notification API.
📑 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.
✏️ Put the link to your API documentation here
To access the Swagger documentation, click here.
📑 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.✏️ Write your text here
For hypermedia, since there is not as much support in JavaScript as in Python, we have used a custom implementation. However, we have used it and we have made it similar to Mason format which was discussed in the exercies.
Some of the reasoning behind selecting this kind of format are:
- Based on json format which is easy to comprehend.
- It was already introduced in the course material
- It has error-handling capabilities
| Task | Student | Description |
|---|---|---|
| template-self | http://localhost:3031/v1/notification/email/template/1" | Getting a single template item |
| template-collection | http://localhost:3031/v1/notification/email/template/" | Getting all templates |
| recipient-self | http://localhost:3031/v1/notification/email/recipient/1" | Getting a single recipient item |
| recipient-collection | http://localhost:3031/v1/notification/email/recipient/" | Getting all recipients |
| Role | Reference URL | Description |
|---|---|---|
| Resources implementation | Kavindu Ravishan | 10 hours |
| Implementation | Achira Hendalage | 10 hours |
| Documentation & implementation | Sameera Gamage | 20 hours |
| Discussion | Everybody | 5 hours |