RESTful API description
📑 Chapter summary
This chapter must provide a good overview of the Web API that your group is going to develop during the course, and some insight into the (imaginary) microservice architecture it will be a part of. You should not focus in implementation aspects such as database structure, interfaces or the request/responses formats. We recommend that you look into existing APIs (see Related work below) before writing the description for your own API.- Understand what is an API
- Describe the project topic API
- Describe how the API would be used as part of a larger architecture
✔️ Chapter evaluation (max 5 points)
You can get a maximum of 5 points after completing this Chapter. More detailed evaluation is provided in the evaluation sheet in Lovelace.📑 Content that must be included in the section
Describe the API you are going to implement. Also describe the larger imaginary architecture that would exist around that API - while you do not need to implement these other components, they will be helpful in imagining context for your API. Your API will be a component that stores, and offers an interface to, some important data in the larger ecosystem. Think about a larger system, and then take out one key piece to examine - this will be your API.
Describe the API briefly and comment what is the main functionality that it exposes. Focus in the API not in any specific application that is using this API. Take into account that in the end, a WEB API is an encapsulated functionality as well as the interface to access that functionality. Remember that your API is just one part of a larger machine. It does not need to do everything. There will be other components in the system to do those things. This course focuses on creating a small API in detail - thinking too big from the start will drown you in work later.
A really short version of an overview for the RESTful Web API could be:
“The discussion forum Web API offers different functionalities to structure non-real-time conversations among the people of a group about topics they are interested in certain topic. Messages are grouped in Threads, that at the same time are grouped in Topics. The messages are accessible to anyone, but posts can only be created by providing credentials of a registered user [...] This API could exist as part of an online learning environment system where it is responsible for offering discussion forum features that can be included in other components of the learning environment. For example, a programming task (managed by a different component) can include its own discussion board managed by the discussion forum API[...]“
✏️ The StudentManager Web API allows administrative personnel of learning institutions functionalities to manage the students and their personal information, along with the grades they achieved in the courses. A picture will also be saved for each student, to allow identification for exams and other activities. All the courses provided by the institution will be saved in the database, along with the professor, the course code and the granted credits. Each student will be associated with any courses they have passed, and information about the date and the grade will be collected. The API is strictly aimed to the administration office, and allows any operation on the students to be performed, course management will be left outside the scope of this API. Employees of the administration office will need a username and a password to access the API, since it gives access to sensitive information. Security clearance and access will be provided by the appropriate entity in the university. The API could be part of the whole administration environment of a University: teachers and room bookings could also be managed through the system using any other technology. Courses could also be managed by a third party, and accessed by the StudentManager server, so they probably wouldn't reside in the same database. Many software tools could be connected to this system, one example is automatically printing the ID cards for new students when they are first registered.
📑 Content that must be included in the section
Define the main concepts and describe the relations among them textually. Roughly, a concept is a real-world entity that is expected to be of interest to users or other services. This section will be a guideline for choosing your resources to implement in Deadline 3. Students should remember that some of the concepts might not be a resource by themselves, but just a part of it (resource property). In this section, students should not describe the RESTful resources, but identify which are the main ideas of the API. Do not forget to include the relations among the concepts.A description of the main concepts for the Forum API could be:
"The API permits users send messages. The forum contains a list of categories and a list of users. Each category specifies a name, a description and a thread. A thread is [...]The forum may contain 0 or more categories… Each category may have 0 or more threads… Users can write and read messages to a forum thread. A user has a profile, basic information, activity information (stores, for instance, all the messages sent by a user, the messages marked as favorites). [...]The user history contains information of the last 30 messages sent by the user.[…]"
Include a diagram which shows the relations among concepts.
This section is important because it outlines the concepts that you will later implement. In particular, the diagram defined here will follow you throughout the project report and you will be adding more details to it.
✏️ The API allows the administration office to store and update information about students and their academic progress. The system contains all the students. Every student has a name, surname, date of birth, social security number and profile picture. All these attributes are mandatory. All the courses offered by the university are stored in the database, with their name, code, teacher and ECTS. All these attributes are mandatory. Students can be associated to any number of exams through asn assessment. Each assessment will store the passing grade and the date of the accomplishment. Each student will have zero or more grades, and each course will have zero or more students that have passed it.
📑 Content that must be included in the section
Describe at least one client and one service that could use your Web API. You must explain here what is the functionality provided by the client/service, and how it uses the Web API to implement this functionality.✏️ One client that could use the API would be a web application that gives access to the stored data, and allows the user to read it, modify it and insert new data. The user could navigate through the database and access information about any of the stored entities, following the links to the associated ones. For example, the user could access one student's details when clicking on their name from the list of all students, and could then view the list of all the exams they passed and from there access the course details. The API allows the user to access any of the stored and entities at any times, edit the stored data, delete stored entities, or insert new ones.
One service that could use the API would be an automated ID card printer. Polling the list of students from the API at certain intervals, the service would recognise which students were added to the system since the last check. The service would then retrieve the details of each student and their profile picture through the API. Once the information has been collected, the service would compose the image of the ID Card with the picture, name and surname, and send it to the appropriate device to be printed on a plastic card that will be issued to the student.
📑 Content that must be included in the section
Find at least one API that resembles the functionality provided by yours. Explain in detail the functionality provided by the API. Classify the API according to its type (RPC, CRUD REST, pure REST, hypermedia driven ...) justifying your selection. Provide at least one example client that uses this API.The purpose of this task is to get more familiar with what an API is. This will be helpful in describing your own API. Therefore, it is recommended to do this section after you have decided the topic of your project but before writing your API description.
✏️
Knowing that we would like to build a Hypermedia Driven API, we started searching for any standard protocols or widely adopted implementations. The best documented and simplest one we came across is HAL, defined by Mike Kelly at Stateless: HAL - Hypertext Application Language. A draft of the formal specification is also available for us to use.
We found three different public APIs that follow HAL. The viagogo API exposes control to the ticket marketplace for third party applications to manage listings. On some resources, the links are used to publish controls, eg.: sellerlisting:delete or sellerlisting:publish, whereas in other places it is used for simple navigation, like first, last, previous and next links. An example client for the viagogo API is GogoKit.
The Artsy API is an immutable database of artists' data meant to be browsed or used in third party applications. Accordingly, each artist will have a link such as artworks or similar_artists giving access to related resources, but no controls are exposed.
Finally, the most complex api, the Arrive API exposes functionality for smart parking, venue and vehicle management, bookings and tickets. This API does not strictly use hypermedia, many controls are only present in their documentation but most important related resources are presented in the _links array. An example of a client using the Arrive API (specifically the ParkWhiz API) is ParkHub, which integrates ticket reservation services for events (Arrive API) and physical parking POS systems in the parking space.
With the definition of HAL, a simple and practical example of HATEOAS and public APIs using and interpreting HAL in different ways, we will be able to choose our best approach for our project, a complex but single-purpose, mutable database.
| Task | Student | Estimated time |
|---|---|---|
| Meetings | All | 1h |
| Repo and Wiki setup | Lorenzo Medici | 0.5h |
| Writing the description | Lorenzo Medici | 1h |
| API usage and relations | Pranav Bahulekar | 1h |
| Related Work section | Daniel Szabo | 1h |