‼️  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 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 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

---

✏️

The relations can be split into two main branches, the one that follows the Students and their Assessments, and the one that follows The Courses and their Assessments. They are almost identical in nature, so only the Student branch will be described. When the requested URL is the StudentCollection endpoint, a link to itself with POST method (add-student) will be exposed. Furthermore, any of the returned Students will carry a self link meant to point to their URL. When following this link, a single Student will be returned, carrying links to the collection, to the related assessments through student-assessments, and to itself with PUT and DELETE methods. Once the student-assessments link is followed, the list of the student's assessments will be provided by the StudentAssessmentCollection endpoint. This endpoint will also return links to the related Student, while each assessment will carry a self link to its StudentAssessmentItem URL. There, there will be links to the Assessment's Course and Student, as well as the collection, and to itself with PUT and DELETE methods.

Since we have a unique endpoint for adding assessments, all entities will also return a link assessments-all to the AssessmentCollection endpoint. This endpoint will expose a link to itself with POST method called add-assessment. This endpoint is present in our API to avoid duplicated code and more convoluted application logic in StudentAssessmentCollection and CourseAssessmentCollection. When requesting a GET from AssessmentCollection, each item will carry a self link pointing to its related CourseAssessmentItem.

To "move" between the three different branches of the API, the students-all, courses-all and assessments-all are used. These will point to StudentCollection, CourseCollection and AssessmentCollection respectively. The former two will point to each other, and to the latter, which will then point to both of them.

The ProfilePictureItem at the top of the image can be reached from the corresponding StudentItem by following the propic hypermedia link. The The ProfilePictureItem then exposes the student link, with the same purpose as in StudentAssessmentCollection.

---

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

---

✏️ The documentation can be accessed at http://localhost:5000/apidocs/ once the server is running locally.
The documentation files are located in the studentmanager/doc subfolder, 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.

---

✏️ We implemented the Hypermedia relations using the Mason mediatype. We chose this mediatype because it was clearly presented during the lectures, and it was the only one we had experience in. It also carried all the features to easily and clearly implement the relations in our resources.

In the API, some custom link-relations were needed. We then introduced a namespace as studman. The custom links introduced are:

• students-all, courses-all, assessments-all: These link point to the three main endpoints of our API, and are necessary for navigating it correctly. Since this depends on our API structure, no suitable relation in the IANA standard was found

• add-student, add-course, add-assessment: These links are used to expose the syntax and requirements for POST methods necessary for adding resources. Again, no IANA standard relation was found to add elements to a collection.

• student-assessments, course-assessments: These links point to the collection of Assessments related to a Student or a Course. Since they are very specific to our API structure, custom relations were necessary.

• student, course: These links point to the related student or course of any AssessmentCollection or AssessmentItem, be it in the Student or Course branch. The use of these custom links stems once more from our specific API structure

• delete: A utility link for expressing deletion of the current resource.

• propic: Link pointing from a StudenItem to the corresponding ProfilePictureItem. This is needed because of our specific API structure.

  Connectedness is achieved in our API by exposing links between the three main branches through students-all, courses-all and assessments-all. Then, links are exposed for moving "up and down" through each chain from the main branch collection to a specific assessment. Then, each entity will link to the AssessmentCollection endpoint. This endpoint could be the most isolated one, but points to StudentCollection, CourseCollection, and each assessment returned points to the respective CourseAssessmentItem. This means that no endpoint is a "sink" in our graph, all points can be reached, and all points expose outgoing links to other resources.

---

Task	Student	Estimated time
Meeting and hypermedia diagram	All	1h
Hypermedia implementation, testing and wiki	Lorenzo Medici	2h
API Documentation Content	Alessandro Nardi	4h
Resource Relations and Justification	Pranav Bahulekar	3h
API Documentation Structure	Daniel Szabo	1.5h