RESTTful API description - HenglinShi/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. 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
The Image Processing Web API offers a various of functionalities for user to process their images. Specifically, user selects a desired image processing approach and submits a job to the system using their credentials, then the system will start the job based on the load. The user is able to retrieve the processing result after the job is completed, again using their credentials. The service of the image processing is not free, every functionality consumes different amount of tokens. Every user has their own account which states their remaining tokens. Certainly, user is able to view their transaction history and even monitor their token consumption within a given period of time.
This project is proposed based on the trend of computer vision applications. On one hand, we can see that image recognition application can much more benefits our work and daily lives. On the other hand, from the entertainment point of view,in recent years, we can see a lot of applications that user manipulate images, for example customizing profile photos. With the gradually matured generative model, there must be more ways and needs about generating interesting images. As a result, we reckon this is a business opportunity and decide to create this service which offers relevant APIs. The service is on-demand, and paid according to the time used, which is a very flexible business mode.
Specially, we will offer many types of APIS:
1 Image Inpainting APIs:
a Face inpainting which will generate a artistically painted image based on the a given image.
b Face replacing which will replace the face in the given image with a cartoon face.
2 Image recognition API:
a Object detection which detects a list of objects in the given image
b Object recognition which will recognize what the image is
c Emotion recognition which will predict the emotion of the person in the given image.
2 Retrieval APIs:
a Retrieving job which returns a list of users' jobs based on the given search criteria.
b Retrieving result which return a list of previous completed results based on the given search criteria.
c Retrieving transactions which will return a list of previous transactions based on the given search criteria.
📑 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
The API permits users to submit job to the server. Each User has an Account and a Authentication Profile. The account stores users' basic information such as name and age, and the token remained which will be costed by running jobs. The authentication profile will only contains users' user name and password.
After the Job has been submitted, it will not be executed immediately, but will be queued and executed according to the sever load. The job can be cancelled at this stage. After the job is being executed, a Transaction record will be created accordingly which states the cost and other relevant information of current job. After the job is completed, a Result will be created based on the id of the job. User can fetch their job status to check if the job is completed, if completed the user can fetch the result of the job.
Each User will have one and only one Account and Authentication Profile. But each User will have 0 or more Jobs, Transactions, and Results. One Job has on and only one Result. The relationship is given based on the diagram below:
📑 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
In our opinions, the first type of uses of our API is through Web users. User can send request thourgh web pages. The second type of uses is mobile application that users send request through mobile apps.
📑 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
In nowadays, there are various service providers offer related APIs. One significant example is the Cognitive Services powered by Microsoft Azure. Actually it provides various types of APIs, but it does have a set of REST APIs. Its REST APIs have following properties:
- Uses url to locate resources.
- Uses HTTP verbs, e.g. GET/POST/PUT/DETELTE/PATCH
- Uses hypertext, json.
- Returns state code
Also, Azure also provide other type of APIs, such as Java, C++.
One of their customer is Uber which uses their service of facial recognition to validating the identity of the drivers which boosts the platform security. Uber has their mobile application so that every driver should identify themselves using the app. The app will receive the user face image, and send the request contains the image through the web API and receive the result.
An additional API is the Cloud Vision API powered by GOOGLE .
| Task | Student | Estimated time |
|---|---|---|
| Overview | Amine ERRAFA | 1 HOUR |
| Entity Design | Henglin SHI | 1 HOUR |
| API uses | Henglin SHI | 1 HOUR |
| Related Work | Amine ERRAFA | 1 HOUR |