Skip to content

RESTful API documentation and hypermedia

Jump to bottom
Ivan Sanchez Milara edited this page Feb 7, 2024 · 11 revisions

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:

  1. 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
  2. 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

Hypermedia implementation

💻     TODO: SOFTWARE TO DELIVER IN THIS SECTION The code repository must contain:
  1. 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).
  2. Necessary scripts to run your server
  3. 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:
  1. 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
  2. The external libraries that you have used
  3. We recommend to include a set of scripts to execute your tests.
  4. A database file or the necessary files and scripts to automatically populate your database.
  5. 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.

✏️ Write your text here

RESTful API documentation

API Documentation

📑  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

Resources allocation

Task Student Estimated time

Report index

Clone this wiki locally