RESTful API description - laurilako/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 SelliX API implements an API for marketplace applications, where clients can query available items in inventory, select favorite items and query users participating in the marketplace.
The API provided by SelliX could exist in online user to user marketplace applications, where it is responsible for the book-keeping related to item listings, users and favorite products. The API handles and stores the relationships between items, users and favorites. Unauthorized clients are able to only query a list of users and products of the API. Authorized clients are also able to create, update and delete items from the API.
The API could exist in a normal web application ecosystem, where developers could make their own clients for accessing the API. With these clients users are able to access the API to store data related to marketplace users, products and transactions. When the authenticated users access the website, they are able to view items listed by other users and get more detailed information about them. Users are also able to create their own item listing, and leave reviews for the existing items. All of the actions presented are handled indirectly through the API.
📑 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 permits users to view, create, edit, delete listing for certain product that they want to either buy or sell. API permits users to buy / sell product and after that they can review the seller / buyer. Seller / buyer is just another user on the platform. Each user has own profile with basic details and product, personal review history that everyone can see. API permits users to view all available products and possibly view them by tags that can be attached to product in its creation phase. Each product is unique and is either available, or sold/bought (not available anymore). With API, user can view all own products or products that user has bought or sold.
Initial diagrams, data model sketch that shows possible relations:
Initial sketch of front-end client views that API permits:
📑 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.When users access the site, they can effortlessly explore featured products showcased on the front page. Upon entering, a client initiates a request to the products route on the lower level. This request retrieves product information from the database and responds to the client accordingly, which then gets presented to the user.
Users have the ability to refine their product search. By entering a specific item key/word or name, the client sends a request to the products/search route. This route systematically examines the products and their attributes, returning only those (as a list) that match the specified criteria.
Product creation is achieved by completing a form on the client. Upon submission, the client sends a post request to the API's products route, which then gets added to the database.
Clients can obtain detailed information about a specific product by sending the API its unique product ID. The API efficiently searches the database and promptly responds to the client with the relevant product details.
Users can modify their created products by submitting a put request to the API. The API, in turn, captures the updated values from the client's request, promptly applying the changes to the products, and responding with a 201 status code to signify successful updating.
📑 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.
- User Authentication: Allows users to authenticate and access their eBay accounts securely.
- Listing Management: Permits users to create, edit, and manage listings for products or services they wish to sell on eBay's platform.
- Search Functionalities: Offers robust search capabilities, enabling users to search for specific items based on keywords, categories, and other parameters.
- Product Reviews: Provides access to product reviews and ratings, allowing buyers to make informed purchasing decisions.
- Messaging System: Facilitates communication between buyers and sellers through an integrated messaging system.
The eBay API falls under the category of CRUD REST (Create, Read, Update, Delete Representational State Transfer) APIs. It allows users to perform CRUD operations on various resources within the eBay marketplace, including listings, user accounts, and product reviews.
An example client that utilizes the eBay API is the GarageSale application for macOS and iOS. GarageSale allows users to create and manage eBay listings directly from their desktop or mobile devices, leveraging the functionality provided by the eBay API for seamless integration with eBay's marketplace.
- eBay Developer Program (https://developer.ebay.com)
- eBay API Reference.(https://developer.ebay.com/api-docs)
| Task | Student | Estimated time |
|---|---|---|
| Writing documentation, planning, research on topic | Konsta Laurila | 6 |
| Writing documentation, planning, research on topic | Bishwas Wagle | 6 |
| Writing documentation, planning, research on topic | Kurosh Husseini | 6 |
| Writing documentation, planning, research on topic | Aleksi Illikainen | 6 |