RESTful 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[...]“
✏️
This API could exist as part of a cooking website where users can find recipes on the platform using different search filters, add and edit their own recipes, and save recipes into a cookbook. The Recipe Web API provides an interface for people to manage recipes and ingredients. Recipes can be added, edited, and removed by the users that created them. Each recipe contains a list of ingredients, cooking instructions and other properties related to the recipe like preparation and cooking time. Each recipe ingredient includes the ingredient's name, a specified amount required for that recipe and its unit of measurement. The user can create cookbooks that are a collection of recipes.
📑 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 users to add, update and remove recipes. These recipes can be added to a collection of recipes called a cookbook. The cookbook would have a name, short description and a list of recipes saved to it. Each recipe contains properties such as recipe name, preparation time, cooking time, meal type, servings and number of calories, as well as a list of recipe ingredients and instructions. An ingredient has a name and can be added if it doesn't already exist. Each recipe ingredient defines a predefined ingredient with the amount and measuring unit required for the specific recipe.
A chef (user) has a basic profile with their username, and are linked to their created cookbooks, their saved recipes (if they were not assigned to a cookbook) and their created recipes.
api/
├── chefs/
│ └── {chef}
│ ├── cookbooks/
│ │ └── {cookbook}
│ └── recipes/
│ └── {recipe}
├── cookbooks/
│ └── {cookbook}
│ └── recipes/
│ └── {recipe}
├── recipes/
│ └── {recipe}
│ └── ingredients/
│ └── {ingredient}
└── ingredients/
└── {ingredient}
📑 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.✏️ Usage Example 1: Recipe Pin Board - A website where people can create and post recipes, as well as compose cookbooks consisting of their favourite recipes. This client webpage could use our Web API as the mechanism to save a collection of recipes and ingredients and it would have a similar interface to websites like Pinterest and Tumblr.
Usage Example 2: Meal Plan App - A web application where people can create dietary meal plans using their own recipes or recipes with their required calories or meal types. This client could be linked to a fitness application that could recommend certain meals based on the user's exercises.
Usage Example 3: Meal Prep - A web application where people can create or find recipes based on the ingredients they have, and plan their meals for the week. Potentially, this client could use the planned meal recipes to create a shopping list of the required ingredients the user needs to buy, and recommend stores to buy them from.
📑 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.
✏️ Spoonacular recipe and food API - This RESTful API uses HTTP requests to interact with its resources and it provides numerous services:
- Semantic search: a search process that uses language processing techniques to analyze a given phrase and carefully search for a recipe.
- Recipe analysis: classifies recipes according to diets, allergies, cuisines, etc.
- Visualizes ingredients: shows the images of ingredients and recipe steps for quicker reading
- Recipe Price Breakdown: it breaks down the prices of the ingredients for users to know the total recipe cost and cost per serving
- Nutritional Information: provides all the nutritional information of the recipe
- Instruction Analysis: breaks down recipe instructions into simple steps, showing images of the equipment or recipe
The systems that utilize the Spoonacular API include SlimFast, Mealplana and Gymmio.
| Task | Student | Estimated time |
|---|---|---|
| RESTful API description | Chubo Zeko | 4 hrs |