RESTTful API description - psaarine/PWP-Pyry_Jari_Markku 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
✏️ The car installment application is designed to serve as an internet variation of a more traditional physical notebook. People can store information into our API and later browse it efficiently using our API:s built-in functions.
Using a more traditional notebook to store information requires lots of mechanical work, you have to search for car models and compare prices manually, which is tiring work and prone to errors. Our API allows you to not only browse that information efficiently but also compare it and share it with your co-workers, family and friends.
📑 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
✏️
Our database is organized by handles contain paymentplans and models. User that has access to handle can submit, edit browse and delete models and paymentplans. Paymentplans contain various information about the transaction. Models contain various information about the carmodel that is to be appended to paymentplan. For each model in the database user can post new paymentplans that are associated with that model. Then third party users such as friends and bussiness partners that have access to that handle can browse and edit information and post new information to the network of users.
📑 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
✏️ A client developed for a car salesman could be designed to first store the information about good deals to our database and then compare and race those deals. Naturally it is of great interest to a car salesman to know which of the deals were best. This way a car salesman could easily get valuable information about his deals, such as lowest price among models and best interest rate among providers. This client would use computers power to COMPARE mathematical data at inhuman speeds.
Another client could be developed for a company that plans on buying multiple cars for representational purposes. For the sake of companys image it would be important that all the cars share the same model and manufacturer. The boss of that company could send his employees to search internet and nearby car magazines for candidates of cars and then save the information to the database. The company could later in a meeting browse this information and decide which of the models all of the employees would be willing to drive.
A Recycling firm could have a database of cars that would otherwise go to melting or junkyard that uses our API. That way people could buy cars cheaply and help the enviroment.
A University could have a network that students can submit their cars for sale or for trade. Our Api could serve as way for people to store this information.
📑 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
Rebilly is a subscription-billing company that created this API to help with various payment related deeds. Rebilly.
This API advertises itself as RESTFul and has in its own words "predictable URLs". This seems to be correct since URLs are categorized logically in a hierarchi fashion, as an example:
/bank-accounts
/bank-accounts/{id}
/bank-accounts/{id}/deactivation
From those URLs it also seems that scoping information seems to go to the URL rather than request body, which is a REST principle. From the documentation we can also see that iformation about an individual item goes to the request body.Documentation
Also that API uses different verbal methods like POST and GET in a manner that is logical. GET is used to getting information and POST for posting etc.
It is to be mentioned that this API seems to be using id-field to differentiate between individual items. This is something I was strictly discouraged from doing.
Another relevant API is Imgur API Documentation. Imgur is an api that allows people to store images and watch and comment on them. Imgur-API:s main user is its browser client that can be seen here. Imgur. Client serves as a way for users to post images and browse other user's collections.
Imgur is related to our work not only because its documentation is a good example for our own project but also because we intend to implement a client that uses the Imgur-api. We intend to link handles model collection into an Imgur profile to allow users to submit and browse photos.
| Task | Student | Estimated time |
|---|---|---|
| Filled RESTful Api description | Jari Jussila | 8h |
| Filled RESTful Api description | Pyry Saarinen | 15h |