RESTful API design - VilleKylmamaa/WorkoutLogAPI GitHub Wiki
๐ Chapter summary
In this chapter, the students must design the RESTful API.The minimum requirements are summarized in the Minimum Requirements section of the Project Work Assignment. Note that if you do not meet Minimum Requirements this section wont be evaluated.- Understand REST principles
- Understand connectedness and/or hypermedia
- Design a small API
- Write API documentation
You have two options:
- Implement the API using a non-hypermedia format (RESTful CRUD). In this case, it is mandatory that all your resources are connected. You cannot get full points in this section if you do not design your API using an hypermedia format
- Using an hypermedia format. Lots of examples provided in Exercise 2. You can get full points. In this case you need to clearly include in the documentation a profile with link relations and semantic descriptors.
The recommended step-by-step process is:
- Identify all the resources to be exposed by the Web API. To that end, students should make an abstraction of the concepts defined in section 1. Be aware that a one-to-one mapping between the resources and the concepts defined in section 1 is not usually the best option. Sometimes it is better to pack several concepts in the same resource.
- Establish the resource hierarchy and assign a URI to each resource.
- Establish relations and possible actions among resources. Create the state diagram of your API.
- Expose each one of the resources to the uniform interface.
-
Design the resource representation using adequate format.
- Define the media type and its extension (if any)
- Define the profiles (if you are using an hypermedia format). Try to reuse existing profiles as much as possible. For instance, utilize schemas defined in schemas.org.
- Do not forget to include the format of the requests. If you are using hypermedia format and the media type does not define the format of the requests, they must be defined in the profile. Otherwise, the request formats must be defined in the documentation.
- Define the format of each HTTP error response, including message body, status code and headers.
- It is recommended to use a hypermedia type for the response. This blog post contains some good recommendations.
โ๏ธ Chapter evaluation (max 25 points)
You can get a maximum of 25 points after completing this section. More detailed evaluation is provided after each heading.๐ Content that must be included in the section
- Fill the table below with a description of the API resources
- Include a state diagram of your application, in which each resource is a state. Describe also the state transitions. To build this diagram you should reuse the diagram created in DL1. You can use online tools such as draw.io or lucidchart to create the diagrams. You have an example in the following image
โ๏ธ Evaluation criteria(max 2.5 points)
You can get a maximum of 2.5 points after completing this section.- Resource table with URLs and short descriptions is provided: 0.5
- State diagram with transitions exists (see below): 0.5
- State diagram follows relationships from DL1: 0.5
- State diagram is correct, states make sense, transitions are clear and all possible transitions documented: 1.0
โ๏ธ This table might serve you as a guide
WorkoutCollection, ExerciseCollection and WeeklyProgrammingCollection are the root level collections, which are also the links available from the API entry point.
There are two linked paths that lead to the SetsWithinWorkout and SetItem, which the state diagram should help visualize:
WorkoutCollection -> Workout -> ExercisesWithinWorkout -> Exercise -> SetsWithinWorkout -> Set
and
ExerciseCollection -> Exercise -> WorkoutsByExercise -> Workout -> SetsWithinWorkout -> Set
I have designed this structure because I considered that when adding workouts the path starting from WorkoutCollection is natural, but when searching for data for a specific exercise, for example for finding all the workouts the exercise has been trained in or for graphing max data entries, it's logical to start from ExerciseCollection.
Some of the resources have two resource URLs because there are two paths to the same resource. They are also represented twice in the state diagram. For example.
Resource description is pushed to the far right because of the long URLs. You might have to scroll right.
| Resource name | Resource url | Resource description |
|---|---|---|
| WorkoutCollection | /api/workouts/ | Collection of all workouts |
| WorkoutItem | /api/workouts/<workout_id>/ /exercises/<exercise_name>/workouts/<workout_id>/ |
A single workout |
| ExerciseCollection | /api/exercises/ | Collection of all exercises |
| ExercisesWithinWorkout | /api/workouts/<workout_id>/exercises/ | Collection of all exercises within a specific workout |
| ExerciseItem | /api/exercises/<exercise_name>/ /workouts/<workout_id>/exercises/<exercise_name>/ |
A single exercise |
| SetsWithinWorkout | /api/workouts/<workout_id>/exercises/<exercise_name>/sets/ /exercises/<exercise_name>/workouts/<workout_id>/sets/ |
All sets done in a specific workout for a specific exercise |
| SetItem | /api/workouts/<workout_id>/sets/<exercise_name>/<order_in_workout>/ /exercises/<exercise_name>/workouts/<workout_id>/sets/<order_in_workout>/ |
A specific set done in a specific workout for a specific exercise |
| MaxDataForExercise | /api/exercises/<exercise_name>/max-data/ | Max data collection for a specific exercise |
| MaxDataItem | /api/exercises/<exercise_name>/max-data/<order_for_exercise>/ | A single max data entry for a specific exercise |
| WeeklyProgrammingCollection | /api/weekly-programming/ | Collection of all weekly programming data |
| WeeklyProgrammingForExercise | /exercises/<exercise_name>/weekly-programming/ | Collection of all weekly programming data for a specific exercise |
| WeeklyProgrammingItem | /api/weekly-programming/<exercise_type>/<week_number>/ /exercises/<exercise_name>/weekly-programming/<exercise_type>/<week_number>/ |
A single weekly programming data entry for a specific week and a specific exercise type |
โ๏ธ Draw here your state machine diagram
๐ Content that must be included in the section
Fill the following table with a description of how your resources are exposed to the uniform interface (GET, PUT/PATCH, POST and DELETE methods). You must describe the action executed in each request. For example, a GET request to the URL /messages/{message_id} "gets the body and the title of a specific message".โ๏ธ Evaluation criteria(max 0.75 point)
You can get a maximum of 0.75 points after completing this section.- The uniform interface shows all possible requests and actions are described for each: 0.75
โ๏ธ This table might serve you as a guide
| GET | PUT | PATCH | POST | DELETE | |
|---|---|---|---|---|---|
| WorkoutCollection | gets all the workout sessions | creates a new workout session | |||
| WorkoutsByExercise | gets all the workout sessions in which a specific exercise has been done | ||||
| WorkoutItem | gets in a specific workout session, including the exercises done within it and the sets done for the exercises | edits the data values in a specific workout session | deletes a specific workout session | ||
| ExerciseCollection | gets all the exercises, including all their max data and the sets done for the exercises | creates a new exercise | |||
| ExercisesWithinWorkout | gets all the exercises which were done in a specific workout | creates a new exercise and adds it to the workout, or adds an existing one if it already exists | |||
| ExerciseItem | gets a specific exercise, including all its max data and the sets done for it | edits the specific exercise | deletes the specific exercise and all its max data and sets | ||
| SetsWithinWorkout | gets all sets done in a specific workout for a specific exercise | Adds a new set to the specific workout for the specific exercise | |||
| SetItem | gets a specific set done in a specific workout for a specific exercise | edits the specific set | deletes the specific set | ||
| MaxDataForExerciseCollection | gets all the max data for a specific exercise | adds new max data entry | |||
| MaxDataItem | gets a specific max data entry for a specific exercise | edits the specific max data entry | deletes the specific max data | ||
| WeeklyProgrammingCollection | gets all the weekly programming data | creates a new weekly programming data entry | |||
| WeeklyProgrammingForExercise | gets all weekly programming data entries for a specific exercise | ||||
| WeeklyProgrammingItem | gets a specific weekly programming data entry for a specific exercise type and week number | edits the specific weekly programming data entry | deletes the specific weekly programming data entry |
๐ Content that must be included in the section
Use any of the tools presented in Exercise 2 (e.g. Apiary) to document the API. Follow the format specified in that exercise also. You can take the TVflix service REST API or Cryptotrading API(created by previous year students) as a model.
For all resources you must cover:
- The possible HTTP methods exposed by this resource
- The headers in the request and responses
- The media type utilized (in the response Content-Type header). If you are utilizing your own media-type you must describe it in the section Own media type implementation.
- If you are using an hypermedia type you must provide the profile utilized, including.
- Link relations. Include methods and format of the requests if they are defined in the media type. Use as much as possible IANA defined relations.
- Semantic descriptors. If you utilize a descriptor used in some other profile (e.g. schema.org) provide the link.
- If you are extending other profiles, do not forget to link to the extended profile.
- The format of the HTTP response body, providing a clear example. If necessary, comment the example.
- The format of the HTTP request body (just for PUT/POST), providing a clear example. If necessary, comment the example.
- The error conditions, status code and format of the error response, providing a clear example.
โ๏ธ Evaluation criteria(max 13.75 points)
You can get a maximum of 13.75 points in this section:- You are using a hypermedia API: 3.0
- Each request has the correct media type: 0.5
- The media type is used according to its specification: 1.0
- Link relations are described (either in the profile for hypermedia types, or in the resource documentation for the CRUD approach): 1.0
- Do not forget you can use link relations from http://www.iana.org/assignments/link-relations/link-relations.xhtml
- Attributes are clearly explained ( either in the profile - for hypermedia types - or in the resource documentation - for the CRUD approach -): 1.0
- Examples are provided for each request: 0.5
- Examples provided for each request do not contain errors: 0.5
- Examples are provided for each response: 0.75
- Examples provided for each response do not contain errors: 1.0
- Examples includes error responses 0.25
- Examples provided in error responses do not contain errors 0.5
- Examples provide all possible/reasonable error responses for each method 0.5
- Examples have correct headers: 0.5
- Profiles are linked in each response (only for hypermedia APIs, CRUD implementation receive 0 points in this section): 0.5
- Examples use correct status codes: 1.25
- Design is coherent: 1.0
โ๏ธ Include here the link to the hypermedia API documentation
https://workoutlogapi.docs.apiary.io/#
๐ Content that must be included in the section
Explain briefly how your API meets REST principles. Focus specially in the four principles: Addressability, Uniform interface, Connectedness, Statlessnessโ๏ธ Evaluation criteria(max 8.0 points)
You can get a maximum of 8.0 points in this section:- The justification is clear and coherent, and shows an understanding of REST principles: 2.0
- The Api is addressable (no errors regarding addressability): 1.0
- The Api uses correctly the uniform interface: 1.0
- The Api does not hold state in the server: 0.5
- The different resources of the API are connected, that is there are not isolated resources: 2.0
- isolated resource is a resource that either is not linked to from anywhere, or doesn't contain links itself
- Protocol semantics are clearly provided either by the response or by the profile (If you are using a CRUD API you won't get points in this section): 1.5
โ๏ธ Write here your text
Workout Log API meets the REST principles.
The API is designed with resource-oriented architecture (ROA). Every resource is addressable and every unit of data has its own unique address which is used to access it. For example, one of the unique addresses for a specific set (SetItem) is: /api/workouts/<workout_id>/sets/<exercise_name>/<order_in_workout>/, where the specific set is accessed through the specific workout in which it was done, the specific exercise for which it was done for, and which order number it was in the workout.
A client using the API will handle everything with the following HTTP requests: GET, POST, PUT and DELETE. All the data from the resources, including error messages, that the client gets is in Mason (hypermedia enabled JSON format). When the client sends data it's always done by providing the data in JSON format, the URL of the resource and the HTTP method. Thus, the API uses uniform interface.
The API is also stateless as no session information is retained by the API. You can make two or more requests in any order to an URL and it always returns the resource data just the same. The history of what the client has done before doesn't matter. Every request and response provides all the information required to complete the interaction.
The API is designed with hypermedia as the engine of application state (HATEOAS) and a client can discover all the available resources it needs through the links provided by the API. There are no isolated resources, as the state diagram above depicts.
Protocol semantics are clearly provided by the response or the profile. Each response includes the API's link-relations and the profile for the resource the client requested.
| Task | Student | Estimated time |
|---|---|---|
| All | Ville Kylmรคmaa | 30h |