RESTTful 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 Game Server Management API provides functionalities for managing a Minecraft game server via role-based access control.
The game server executable itself is distributed as a JAR file by Mojang. It normally lives on a web host and accepts game client connections from a specific port. Because the game server code is proprietary, all game configuration needs to be done via predefined commands. They allow you to assign users as "operators" who can execute any command, but what about giving users partial operator rights to execute a subset of commands?
Luckily, running the executable starts a terminal session that outputs internal logs, as well as accepts input similar to what you would do in-game when sending commands. The main goal of this API is to wrap the executable into custom code and expose the terminal via our own API. This way we can intercept the commands and enable more granular control of what users can do. In addition we can expose parts of the web host for managing server files and executable lifecycle without logging into the host.
The API consists of two separate services: the Users API and the Game API.
The Users API is the main focus of this course because it's a better fit for REST and hypermedia. It enables users to authenticate into the system with assigned authorities. Any user can authenticate and modify their own basic information, but other user management functionality is restricted to specific roles.
Depending on the user's authorities, an authenticated user can call the various endpoints provided by the Game API to, for example, read game server logs, modify its configuration files or send various game commands. In the context of this course, the Game API is the auxiliary service.
📑 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 operations on users, roles and privileges. Each user represents an end user with unique credentials (username/password). In practice the username is used for identifying users in a human-friendly way, but internally, database-managed row IDs are used for this.
User credentials can be used to login and obtain a bearer access token for stateless access across the system. For security reasons, each token may be revoked which stops the system from accepting them (e.g. logout). They also expire after a predefined amount of time has passed, requiring another login.
The token by itself is not enough to authorise a user to do anything. It simply acts as a temporary proof of authentication to avoid having to input credentials constantly.
To do operations on users (or the game in the auxiliary API), a user needs "authorities". They can be either roles or privileges.
Roles are simple named entities that grant associated users access to different parts of the system. These are predefined for each endpoint, but their associations to users can be modified. Each user can have 0..n roles at any time. An example would be the "ADMIN" role which grants access to any operation within the system, including modifying other users' roles.
For more granular control, each role may also be associated with 0..n privileges. Similar to roles, privileges are simple named entities. Unlike roles, privileges have a "domain" which indicates an area of the system they apply in. For example, a "COMMAND" domain would mean that this privilege is applied only when a user is doing something with game commands. For example, we can define a privilege that allows users with the associated role to execute a specific game command, as long as their roles grant them access to an endpoint that accepts commands.
Roles can be thought of as groups of privileges, and are normally what defines the exact operations a user may access when implementing role-based access control (RBAC). In this system however, roles are the main way of authorisation, and privileges bring finer control only where it is needed.
Both user-role and role-privilege associations are nothing but a tuple formed from their unique identifiers.
📑 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.A web or mobile client may provide an interface for managing users via the Users API. Another service that relies on authentication and/or authorisation may call the Users API service to check for a user's authorities before they are allowed to do something. Although the Users API here is meant to be used together with the Game API, it is generic enough that no specific use case is required.
📑 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.
The Auth0 Management API is a CRUD REST API allowing user, access and authority management. Users, roles and privileges can be searched, created, modified and deleted. Users can login using various methods such as username/password or OAuth2 authentication. The latter can be integrated with an IDP such as Google.
It is not a pure REST API because it doesn't implement hypermedia. As far as I understand, it offers stateless operations as well via stateless session cookies (i.e. all session data is stored on a cookie on the client), but this is not their recommendation. Using it purely as an OAuth2 authorization server will also create at least a temporary session required for the OAuth2 flow. So I would say it's not a purely stateless API either.
The API is quite comprehensive so organisations may use it to authorise employees into their internal systems, e.g. healthcare systems.
| Task | Student | Estimated time |
|---|---|---|
| Everything | Janne Tahkola | ~2 hours |