RESTful API documentation and hypermedia - LassiHeikkila/taskey GitHub Wiki

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 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 mandatory that all your resources are connected. 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 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.

RESTful API documentation

Resource relations

📑  Content that must be included in the section Include a state diagram of your application, in which each resource is a 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

State diagram

API design

📑  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.
  • 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 format of the HTTP response body, providing a clear example. If necessary, comment the example.
  • The format of the HTTP request body (just for PUT/POST), providing a clear example. If necessary, comment the example.
  • The error conditions, status code and format of the error response, providing a clear example.

API is documented using OpenAPI format. Source file can be found here.

API documentation can also be viewed here.

Hypermedia Implementation

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

Hypermedia is not used.

Resources allocation

Task Student Estimated time
Document API Lassi Heikkilä 30h
Write remaining documentation Lassi Heikkilä 12h
⚠️ **GitHub.com Fallback** ⚠️