API documentation and hypermedia

Important information for Deadline 4

‼️ This chapter should be completed by Deadline 4 (see course information at Lovelace)

📑 Chapter summary

In this chapter, the students must modify their API to use hypermedia following REST principles and 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.

SECTION GOALS:

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 18 points)

You can get a maximum of 18 points after completing this section. More detailed evaluation is provided in the evaluation sheet in Lovelace.

Hypermedia

Resource relations

📑 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

stateDiagram-v2
    [*] --> Users: GET /users
    Users --> User: GET /users/{id}
    User --> UpdateUser: PUT /users/{id}
    UpdateUser --> User
    User --> [*]: DELETE /users/{id}
    
    [*] --> Teams: GET /teams
    Teams --> Team: GET /teams/{id}
    Teams --> CreateTeam: POST /teams
    CreateTeam --> Team
    Team --> UpdateTeam: PUT /teams/{id}
    UpdateTeam --> Team
    Team --> [*]: DELETE /teams/{id}
    Team --> TeamMembers: GET /teams/{id}/members
    TeamMembers --> CreateTeamMember: POST /teams/{id}/members
    CreateTeamMember --> TeamMember
    TeamMember --> UpdateTeamMember: PUT /teams/{id}/members/{user_id}
    UpdateTeamMember --> TeamMember
    TeamMember --> [*]: DELETE /teams/{id}/members/{user_id}
    
    [*] --> Projects: GET /projects
    Projects --> Project: GET /projects/{id}
    Projects --> CreateProject: POST /projects
    CreateProject --> Project
    Project --> UpdateProject: PUT /projects/{id}
    UpdateProject --> Project
    Project --> [*]: DELETE /projects/{id}
    Project --> Tasks: GET /tasks?project_id={id}
    Tasks --> Task: GET /tasks/{id}
    
    [*] --> Tasks: GET /tasks
    Tasks --> Task: GET /tasks/{id}
    Tasks --> CreateTask: POST /tasks
    CreateTask --> Task
    Task --> UpdateTask: PUT /tasks/{id}
    UpdateTask --> Task
    Task --> [*]: DELETE /tasks/{id}
    
    %% Optional connections to show better connectedness
    User --> Teams: GET /users/{id}/teams
    Task --> Project: GET /projects/{id}

Hypermedia implementation

💻 TODO: SOFTWARE TO DELIVER IN THIS SECTION

The code repository must contain:

The source code of the RESTful API incorporating hypermedia. The source coude should be documented using the same quality criteria in Deliverable 3. Please, remember to include original source if you have not written the code (even if you have used an AI).
Necessary scripts to run your server
The README.md file with all the information described in the Deliverable 3.

✏️ You do not need to write anything in this section, just complete the implementation.

RESTful API testing using hypermedia

💻 TODO: SOFTWARE TO DELIVER IN THIS SECTION

The code repository must contain:

The code to test your RESTful API (Functional test)
- The code of the test MUST be commented indicating what you are going to test in each test case.
- The test must include values that force error messages
The external libraries that you have used
We recommend to include a set of scripts to execute your tests.
A database file or the necessary files and scripts to automatically populate your database.
A README.md file containing:
- Dependencies (external libraries)
- Instructions on how to run the different tests for your application.

Do not forget to include in the README.md the instructions on how to run your tests. Discuss briefly which were the main errors that you detected thanks to the functional testing.

Remember that you MUST implement a functional testing suite. A detailed description of the input / output in the a REST client plugin.

In this section it is your responsibility that your API handles requests correctly. All of the supported methods for each resource should work. You also need to show that invalid requests are properly handled, and that the response codes are correct in each situation.

✏️ Most important part of this section is completing the implementation. Write down here a short reflection on the main errors you have solved thanks to the functional tests.

Justification on Hypermedia Implementation

📑 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.

The application/json media type was selected for our Flask web API project due to its simplicity, wide support, and alignment with RESTful API design principles.

For our hypermedia API, JSON enabled us to embed links directly in responses (via the _links) without requiring HAL or JSON-LD, making it a natural fit for implementing HATEOAS principles.

Custom Link Relations

We implements several custom link relations that aren't part of the IANA standard registry. These, however show specific relationships and actions in our project:

update: Update was used across almost all resources (projects, teams, tasks, users, team members) to indicate where a resource can be modified via PUT requests (perhaps we could have used edit here but update reflects it better).
delete: Applied to all main resources to clearly signal endpoints that support DELETE operations. No IANA standard relation explicitly denotes a DELETE action.
members: Used in team resources to link to the team members endpoint (e.g., GET /teams/{id}/members). This project-specific relation enables clients to discover and manage team membership.
add_member: Indicates a POST action to add a new team member. No IANA relation exists for this specific domain action.
create: Denotes POST actions to creating new resources. While IANA has "create-form" which could have been used here.
team: Links from a team member back to the parent team. This custom relation aids navigation in the team membership context.
member: Links to an individual team member's details or actions, clarifying relationships in the team context.
projects: Used specifically after deletion to guide clients back to the projects list, providing clear post-action navigation.

Connectedness

Our API achieves full connectedness through an implementation of HATEOAS principles. This makes sure that the clients can navigate the entire API without previous knowledge of its structure:

Hypermedia Controls

Every resource response includes a _links object with relations like "self," "update," "delete," "collection," and domain-specific links. For example, a project response includes links to related tasks.

Cross-Resource Navigation

The API connects related resources through meaningful links. Projects link to tasks, teams link to members, and team members link back to teams. This creates a network of connections that clients can go through without changing the URLs manually.

Complete Resource Lifecycle

For each resource, the API provides links for the entire lifecycle - creation, retrieval, updating, and deleting. After actions like deleting, responses include links to next steps.

No Dead Ends

Every endpoint in our API provides navigation options to related resources or actions, ensuring there are no dead ends.

Consistent Link Structure

Links are generated dynamically using Flask's url_for with _external=True, ensuring absolute URLs that work across environments.

State Transitions

The API has state transition with links. For example, a user can move from viewing a team to managing its members, updating a member's role, and adding new members, all of them guided by hypermedia links.

RESTful API documentation