RESTTful API description - Pepetti/PWP 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. 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.In this Chapter you must describe JUST the RESTful API, NOT THE CLIENT. Remember that client and Web API should be totally decoupled.
- Understand what is an API
- Describe the project topic API
- Describe how the API will be used in the project
✔️ Chapter evaluation (max 8 points)
You can get a maximum of 8 points after completing this Chapter. More detailed evaluation is provided after each heading.📑 Content that must be included in the section
Describe the Web API briefly and comment which is the main functionality that it exposes to clients. Focus in the Web API not in the application which is using this API. Take into account that in the end, a WEB API is an encapsualted functionality as well as the interface to access that functionality. This section CANNOT include a description of an application or client that uses the API.
Justify also why you want to implement this API. Comment why a developer would like to integrate this API into their application. Try to "sell" the API to your potential customers.
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 [...] Clients using this service may implement applications similar to [...]“
Remember: The general description IS NOT just a description of the functionality. Try to market your API to potential customers.
✔️ Evaluation criteria(max 2.0 points)
You can get a maximum of 2 points in this section- The description is clearly written and explains what the API is for: 0.5
- The description includes a clear justification of why this project is useful. Why do you want to build this API: 0.5
- The description describes an API - not an application or client: 1.0
- This means that the description is written in terms of the functionality it makes available for clients, and internal working of the API
- tip: don't think about human users when writing the description - think about machines
✏️ The sports tracker Web API makes possible to save and keep track of every sport activity desired in one place. With the help of this project, we can provide a simple and much easier way to see the progress made in different kind of sport activities. The API makes it possible for developers to create useful sport tracking applications. This way the user doesn't have to carry a notebook and a pen to make the markings with. Web API itself allows different kind of operations to be done such as adding, deleting or modifying different kind of activities and routines. Registration is required, so user can be authenticated and be shown the correct data.
📑 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. This section will be used in Deadline 3 to generate the list of resources. 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 easily 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.
✔️ Evaluation criteria(max 1.5 points)
In this section you can get a maximum of 1.5 points:- Concepts are named and described: 0.5
- Relations among concepts is clear: 0.5
- A diagram that shows relations between concepts is provided: 0.5
✏️ Write here your text and draw the diagram The API permits user to add, remove and modify different routines. A routine is a sports activity that contains information dependent of the activity type. For example a gym routine might be constructed of multiple collections for example squats (the set information, number of reps in each set etc). The activities are organized by date which in it's own is a collection that contains the activities done that day. A day does not exist for the user unless the user has marked done or planned activities for the day. A day collection can have 1 or more activities. User itself consists of basic information such as name (first and last) and e-mail address and the user has its "day" collections. The user can have 0 or more days.
📑 Content that must be included in the section
Describe at least two clients that could use your Web API. You must explain here which is the functionality provided by the client, and how use the Web API to implement this functionality.✔️ Evaluation criteria(max 2.0 points)
In this section you can get a maximum of 2 points- The client descriptions are written clearly and explain what they are for: 0.5
- Descriptions outline what parts of the API each client uses, and how: 1.0
- At least two more examples of clients are provided (1-2 sentences per client):0.5
✏️ Mobile client and web client.
Mobile client is useful when user wants to make changes to different routines when doing a particular exercise. Therefore, user doesn’t need to use the web application or desktop version afterwards rather user can make changes on the go. Mobile client uses the parts of the Web API that allows user to add, remove or modify different routines. HTTP protocol is used to gain access to the Web API.
Web client comes handy in situations, where gym companies offer personal trainer services. Their job is to plan gym routines for their clients and follow their progress. User inserts data to the Web API and the same data is visible in the web client used by the personal trainer. Web application uses the same parts of the Web API as the mobile application. Web client also uses the HTTP protocol to gain access to the Web API.
📑 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.
✔️ Evaluation criteria(max 2.5 points)
You can get a maximum of 2.5 points in this secton:- The selected API is similar or related to the project topic: 0.5
- The API classified correctly, and is described in terms of offered functionality: 1.0
- An example of a client that uses this API is provided, explaining briefly what it does: 0.5
- An additional API is provided 0.5
✏️ The API we chose for a close example of our own planned API is Todoist API (API documentation). The Todoist API offers functionalities for a user to structure different projects and tasks in a meaningful way. The API provides a way to give tasks and projects priority flags to order different tasks accordingly for the day. The API offers a way to plan tasks and projects ahead to remind the user of different tasks. The API accepts get, post and delete requests. The API uses post requests when altering a task.
This API is similar to our Sports tracker API in the way that the sports tracker works basically the same way, but not with projects or tasks. Rather our API can be used to add done sport routines and plan ahead new routines.
The API works on CRUD basis. The API can Create, Read, Update and Delete posts. The Todoist API is basically a more advanced to-do list API. Meaning that there are functionalities to add tasks, remove them, modify them (for example the due date or priority) and mark them complete. Just as in a to-do API.
A Windows desktop version of the client can be found here, a web based version can be used for free at the Todoist website
Task | Student | Estimated time |
---|---|---|