RESTTful API description - LassiHeikkila/taskey GitHub Wiki
📑 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[...]“
High level overview of taskey is that it will be a task scheduling service that can be used as a simple way to perform actions connected computers.
It will have a REST API to configure devices, tasks, user accounts & organizations.
taskey is not intended for continuous workloads or as a remote access mechanism. More like configuring a cronjob remotely.
Example use cases:
- register a raspberry pi on the service and use the service to toggle output pins to turn on lights
- connect a bunch of computers and schedule backups to be taken at the same time everyday
- schedule & adjust local home automation system that is otherwise offline
📑 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.
Users can retrieve a list of machines they are authorized to use.
Users can only interact with resources if they are part of the organization that owns the resources.
Users can define tasks and store them with the service.
Users can assign those tasks to be performed on a schedule by registered machines.
Users can also execute tasks on-demand on registered clients that are online.
Computers can register themselves to be clients on the service, belonging to an organization.
Registered clients can use the REST API to fetch tasks and schedules belonging to them.
Registered clients should then execute those tasks based on the schedule or on-demand.
Registered clients will periodically check for latest schedule information, download new task definitions, etc.
Registered clients will also periodically let the service know that they are online.
When registered client executes a task, it will tell the service what the outcome was.
Tasks can be pretty much anything that a computer can do, but support will be implemented for doing HTTP requests, as well as executing commands and scripts.
Registered clients will be running a daemon that performs the necessary communication with the service, keeps track of schedule, and executes the tasks.
Concept diagram:
Overall architecture:
Detailed look at application design:
📑 Content that must be included in the section
Describe at least two clients or services 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.First client is the human user configuring what they want to happen.
The user may define tasks by POSTing a task definition to the /task endpoint.
The endpoint will naturally support modification and deletion using PUT and DELETE methods.
The endpoint will also support fetching of task definitions using the GET method.
The user may assign tasks to be performed on a schedule by POSTing a schedule to the /schedule endpoint.
Schedule fetching can be done by sending a GET request the the endpoint.
Modification and removal of a schedule is done with PUT and DELETE requests to the endpoint.
The second client is the machine where tasks should be executed.
A daemon running on the machine will periodically GET the machine schedule from the service.
When a task is performed, the daemon will POST the outcome to the service /result endpoint.
📑 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.
There is cron-job.org which is functionally similar to taskey, except that it runs the jobs on the server, not on a target machine.
The API there provides endpoints for configuring jobs, managing user accounts, and viewing job execution history.
API seems to be a CRUD style API, as each request done by the frontend looks to be a POST request to the backend with requested action specified in a header field.
This can be seen here.
The API is implemented in PHP, which I'm not that familiar with, but it seems there are individual endpoints defined for every possible action here: source.
For example, for managing jobs, there are CreateJob.php, UpdateJob.php, DeleteJob.php, CloneJob.php, and GetJobs.php.
The API is used by the same project's frontend.
There are also several "remote control" type apps, as well as remote desktop software, but they are GUI based tools used for controlling one machine at a time.
Of course, regular cron exists as well, but that requires direct access to the target machine and knowledge how to use it.
| Task | Student | Estimated time |
|---|---|---|
| Planning | Lassi Heikkilä | 10h |
| Documentation | Lassi Heikkilä | 6h |