RESTTful API description - GoJamie/PWP GitHub Wiki

Important information for Deadline 1

‼️  This chapter should be completed by Deadline 1 (see course information at Lovelace)

📑  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.

Chapter GOALS:

  1. Understand what is an API
  2. Describe the project topic API
  3. Describe how the API will be used in the project
✔️     Chapter evaluation (max 8 points) You can get a maximum of 8 points after completing this Chapter. More detailed evaluation is provided after each heading.

RESTful API description

Overview

📑  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 2.0 points) You can get a maximum of 2 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: 1.0
    • 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 text

Event API offers different functionalities to manage events for people with similar interests to gather around. Each event contains information about topics, time, location, requirements and participating users. Events can be created, joined, recorded and rated by users. Event API provide search functionality for users who's looking for events with interesting topic. This search functionality provide multiple filter options such as location, time, topic and organizer's infomation to get more precise results. Also, Event API can do recommendations to users based on their information and history of attending events. Developers can use this API to create meeting applications with different topics such as music, sports, techical salons, etc. Our API is an API for people who have common interests and hobbies to meet in real life.

Main concepts and relations

📑  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

Event API combines events with users. Users have different attributes to store name, location, picture, history and interests. Users also can choose their hobbies and location as their labels in order to get acquainted with people who have some interests and are in the same city. We also can recommend new friends to users according to labels. Users can choose whether to open historical events and search history which helps us recommend events that match their interests to them. These attributes are closely related to the user's information acquisition.

Each event contains information about topics, time, location, requirements and participating users. Each user can select 0 or more events, but each event must have at least one user to participate. Users can choose to create an event or join an existing event. The creator of the event can manage the event after creating.

Relationship

API uses

📑  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 2.0 points) In this section you can get a maximum of 2 points
  • The client descriptions are written clearly and explain what they are for: 0.5
  • Descriptions outline what parts of the API each client uses, and how: 1.0
  • At least two more examples of clients are provided (1-2 sentences per client):0.5

✏️ Write here your text

People use the event API to create different activities based on different interests and hobbies. We created multiple clients by using the event API. For example, music client and sport client are used to explain this. Client includes topics, time, location, requirements and participating users. Actually, the client can be a music software. The API in music software has different topics as classical music, concert musician recruitment and pop music exercises, etc. We can also add a performance display function based on the characteristics of the music event.

Outdoor sports software can be another client which uses our event API. The API in sport is prepared for those who like sports to meet group activities. For sports activities need many people to participate such as basketball, football and volleyball, the sport event is set to provide convenience for them.

Related work

📑  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

The selected API is similar or related to the project topic

Our selected API is facebook's Grap API, where the user is able to create events and other people are able to see the event and whether they want to join or not. The API is related to our project by having a similar structure. In the both API's the user is able to create events, join them and also delete. But our events are mainly related to music, where the Facebook API the user is able to create any kind of event.

Graph API functionality

Definition of Graph API is an API that models the data in terms of nodes and edges(object and relationships), which allows the client for interacting with multiple nodes in a single request. For example, the excited server holds data on authors, blog post and comments, where the client wants to get the author and comments for a specific blog post. In this case, the REST API would have to create 3 HTTP request /post/1, /author/5 and /post/1/comments. The client would do the same operation with Graph API by formulating the call so three resources would get pulled at once. link for API: https://developers.facebook.com/docs/graph-api

Client example

The main client of the API is facebooked themselves. With the API the users can create an event by giving the subject, location, description, time and whether the event is public or private. After the event has been created other users are able to see the events and also can join the event based on their taste. Our additional API would be People API which is created by NationBuilder, that could be used for meeting people for specific purposes.

Resources allocation

Task Student Estimated time
API uses Bangju Wang 1 hours
Related Work Nechir Salimi 1 hours
Overview Hao Ban 1 hours
Main concepts and relations Team Work 2.5 hours
⚠️ **GitHub.com Fallback** ⚠️