API description - jpehkone21/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, 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[...]“
The purpose of the project is to create an API, that offers fun quotes from made up characters to give a spark of motivation for the day. There are quotes for different moods (e.g. happy or sad), from different characters (e.g. cat or alien). Users can create new characters and add new quotes for them. This API could exist for example as a part of mobile application or browser extention, giving encouraging quotes throughout the day. Users could also ask for a quote from a specific character or for a specific mood. The application could offer a user fun user interface and automatically generated quotes randomly during the day. By following specific characters, the user will be notified after a new quote has been added. Users could also create their own characters in the application, and come up with new creative quotes for them. This would create an engaging environment and unifying community around the application and its characters. The browser extention could give pop-up quotes during the day to lighten the mood.
📑 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.
This API allows users to create made-up characters and add quotes for them, and other users can then find and read these quotes from characters. The characters are divided into creatures, animals and humans. The user can choose if they want the quote from a creature, an animal or a human, then they choose the specific individual or random individual from the collection. After choosing the individual they will add their current mood as a parameter, using scale 1 to 5, and then the API will give the user quote fitting that mood.
The characters has been divided to creatures, humans and animals. New characters can be added to these categories by the user. User can find a specific character's profile with its name. Specific characters can be edited or deleted. User can get all quotes from specific character or limit the results by giving e.g. mood as a parameter. New quotes can be added under the specific character. Each quote has an ID and quotes can be edited or deleted by using the set ID.
We will have these 4 models, as seen in the picture above; creatures, humans, animals and quotes. They all have six properties, excluding quotes that have three. They will be the tables in our database. Each character has a unique name and other properties which contain information about the character. The characters can have a "picture" of them, which at this point iare going to be a ascii art. All of them also have a list of quotes, which are stored in a separate table. The quotes are identified with an unique id. The character's name (the one who owns the quote) is also going to be stored with each quote.
Above is our first design of the general system architecture. There is the Web API, the client application, and an auxiliary service. The client application sends HTTP requests to retrieve or modify resources in the server. The Web API processes those requests and generates HTTP responses.
📑 Content that must be included in the section
Describe at least one client and one service 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.We will have a command-line client in our project. The user will be able to get/edit/delete specific quotes or characters and add new ones. The client asks the user for the parameters and can make a request to the API. One service that could use this API is a mobile application that fetches the API for new quotes automatically. The API is useful for users who want a quick motivational quote without a full UI.
A service is another application (not a user-facing client) that uses our Web API to perform tasks automatically or in the background. An example could be a translation service that could fetch quotes from the API and store translated versions in another system.
📑 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.
We found API called Zen Quotes API (https://zenquotes.io/). This API generates quotes from e.g famous people or other authors. User can browse quotes by authors or keywords. When searching for author, it displays all quotes from the author. Same with keywords, it displays all quotes that has the keyword. In the site there is links that displays e.g quote of day or just random quote. This API has it's own website client where users can search the quotes.
Justification: The Zen Quotes API is a REST API because it uses simple HTTP requests (like GET) to fetch quotes. It doesn’t store any information between requests - each one is independent. The API sends back data without needing any special procedures. This explains why the Zen Quotes API is classified as a REST API.
Client: An example client that uses the Zen Quotes API could be a mobile app that displays a new quote each day.
We plan to use AI to generate the quotes for our API.
| Task | Student | Estimated time |
|---|---|---|
| ideation | Johanna | 4h |
| ideation | Iina | 4h |
| ideation | Iiris | 4h |