RESTful API description - VilleKylmamaa/WorkoutLogAPI 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 7.5 points)
You can get a maximum of 7.5 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 1.75 points)
You can get a maximum of 1.75 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: 0.75
- 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
✏️ Write here your description
Workout Log API provides functionalities to build many kinds of workout logs. It offers a robust database structure to store all the useful data from workouts. The API is built with flexibility in mind and so most data columns are nullable so that the client can choose which ones to utilize. It can be used to build workout log applications for either strength/hypertrophy training or cardio training, or both.
A Workout contains the trained Exercises and the Sets done for that exercise. Sets store data relevant to either lifting weights or cardio training. Exercises can contain MaxData which can be used to store training, estimated and tested max data to be used for a training program or easily track progress over time. There is also the WeeklyProgramming resource which can be used as a tool to help write training programs to applications.
📑 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
A workout contains exercises for which sets are recorded. An exercise could be a strength exercise such as barbell squats for which an user might want to log the weight used, repetitions achieved, repetitions in reserve (RIR) and rate of perceived exertion (RPE) for each set, or an exercise could be a cardio exercise such as cycling for which an user might want to log duration, distance, average heart rate, max heart rate and RPE for each set. For lifting, the weights used and repetitions achieved will always be recorded, but some trainees never use RIR or RPE. For cardio, one might only want to record either duration or distance.
A workout may contain 0 or more exercises and an exercise may be performed in 0 or more workouts. Within a workout, 0 or more sets could be performed for each exercise.
For lifting, an user might want to record data about exercises' training max, estimated max and tested max. Tested max is an actual maximum weight that a trainee has lifted. Estimated max is an approximation of an actual max, calculated from a maximal set of multiple repetitions. Training max is something used for training programming purposes, it's just a number from which to calculate workout weights, and it could in reality be much more or much less than an actual max. Date for max data is important for the purpose of tracking progress over time.
Exercises can also have programming. Programming tells the trainee how many sets to do, for how many repetitions or for how long, possibly with what RIR or RPE. The same programming can be used for many exercises or it could be different for each exercise.
📑 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 1.75 points)
In this section you can get a maximum of 1.75 points- The client descriptions are written clearly and explain what they are for: 0.75
- Descriptions outline what parts of the API each client uses, and how: 0.5
- At least two more examples of clients are provided (1-2 sentences per client):0.5
✏️ Write here your text
A fully fledged gym client that includes a workout program utilizing the programming functionality and graphs for the progress of each exercise utilizing the max data functionality. When logging workout sessions the client autofills as much data as possible, such as exercises to be done, set count, weight and rep goals, based on the workout program and then calculates possible changes in the training max based on the user's entry for future workouts.
A minimalistic cardio client that mainly cares about logging a cardio exercise and it's duration, distance and average heart rate, just sticking to the workout, exercise and set functionalities. It offers some additional data such as graphs about total duration or distance traveled in each exercise over a certain time period.
📑 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
✏️ Write here your text
Link to wger API documentation: https://wger.de/en/software/api
Link to wger GitHub: https://github.com/wger-project/wger
wger Workout Manager is a free, open source web application that manages the user's exercises, workouts and nutrition. It also provides a REST API with full read and write access to all data for easy integration with other projects and tools.
The functionalities provided by the wger API are workout log, nutrition log and an exercise database. Just like my project, the workout log is for recording data about workouts, data such as session duration, date, exercises done, weights, sets, reps, RIR. The nutrition log is for having a nutrition plan and having ingredient and meal items with data such as calories, fat, carbohydrates and protein with which to log your daily nutrition. The exercise database is for general information about exercises such as the muscle groups used in a certain exercise and description of how to do the exercise.
The API is a REST API, as advertised. A client makes a HTTP request to a URL hosted by the API client server which returns a response. https://wger.de/api/v2/exercise/ for example is an endpoint for exercise objects in JSON. The API is stateless as no session information is retained by the server and you can make two or more requests in any order to an URL and it always returns the resource state just the same. According to the documentation, the data is cacheable so accessing or using is faster than performing many different requests. The system is also layered as the client receives only a JSON document with the requested data, and thus the client doesn't need to know whether it's communicating with the actual server or a proxy.
Some hypermedia controls are utilized. For example, in the endpoint for exercise objects https://wger.de/api/v2/exercise/ there are controls for pagination: "next" and "previous". Each page is limited to 20 exercises and "next" is a link to the next 20 and "previous" to the previous 20.
Link to wger client: https://wger.de/
On the wger homepage click "TRY IT NOW" for a free demo without registration. The client utilizes the API for logging workout and nutrition data I described above and presents the data in useful form such as graphs. Of course, it also has the exercise library utilizing the exercise database.
Link to Fitbit Web API documentation: https://dev.fitbit.com/build/reference/web-api/
Fitbit is a company that makes smart watches, activity bracelets and smart scales and the web API is for accessing data from them or manually entered logs. One could integrate data from the mentioned devices into a workout log client. This is also a REST API where the client makes a request to the stateless API client server which returns cacheable JSON data.
This API also utilizes some hypermedia. For example, on page https://dev.fitbit.com/build/reference/web-api/activity/ there's pagination.
Link to example client: https://towardsdatascience.com/using-the-fitbit-web-api-with-python-f29f119621ea
It's a tutorial how to make a client using the API to fetch data from the user's Fitbit device and use it in a client.
| Task | Student | Estimated time |
|---|---|---|
| All | Ville Kylmämaa | 10h |