RESTful API documentation and hypermedia - talha469/PWPProject GitHub Wiki
📑 Chapter summary
In this chapter, the students must document their RESTful API. The minimum requirements are summarized in the Minimum Requirements section of the Project Work Assignment. Note that if you do not meet Minimum Requirements this section wont be evaluated.- Understand connectedness and/or hypermedia
- Write API documentation
You have two options:
- Implement the API using a non-hypermedia format (RESTful CRUD). In this case, it is recommended that all your resources are connected (linking to other resources). Anyhow, you cannot get full points in this section if you do not design your API using an hypermedia format
- Using an hypermedia format. Lots of examples provided in Exercise 3. You can get full points. In this case you need to clearly include in the documentation a profile with link relations and semantic descriptors.
✔️ Chapter evaluation (max 15 points)
You can get a maximum of 15 points after completing this section. More detailed evaluation is provided in the evaluation sheet in Lovelace.📑 Content that must be included in the section
Include a state diagram of your application, with all the application states. Each resource must be an application state. Describe also the state transitions. To build this diagram you should reuse the diagram created in DL1. You can use online tools such as draw.io or lucidchart to create the diagrams. You have an example in the following image📑 Content that must be included in the section
Use any of the tools presented in Exercise 3 to document the API.
For all resources you must cover:
- The possible HTTP methods exposed by this resource
- The headers in the request and responses
- The media type utilized (in the response Content-Type header). If you are utilizing your own media-type you must describe it in the section Own media type implementation.
- The format of the HTTP request body (just for PUT/POST), providing a clear example. If necessary, comment the example.
- The format of the HTTP response body, providing a clear example. If necessary, comment the example.
- The error conditions, status code and format of the error response, providing a clear example.
-
If you are using an hypermedia type you must provide the profile utilized, including:
- Link relations. Include methods and format of the requests if they are defined in the media type. Use as much as possible IANA defined relations.
- Semantic descriptors. If you utilize a descriptor used in some other profile (e.g. schema.org) provide the link.
- If you are extending other profiles, do not forget to link to the extended profile.
✏️ https://app.swaggerhub.com/apis/TALHAARSHAD39/video-streaming_api_open_api_3_0/1.0.11 All the methods have request examples with required params if any and response have hypermedia documented in above swagger link
Base URL for the API is as follows
https://developmentapi.deldiosmotorclubadmin.com
📑 Content that must be included in this section. Fill this section if your API uses hypermedia
Declare your chosen mediatype, and provide your reasoning for choosing that mediatype. For each custom link relation defined in your API's namespace, explain why it was needed (i.e. why there wasn't a suitable relation in the IANA standard). Explain how Connectedness is achieved in your API.✏️ Write your text here Let's naviagte through the API and discuss the reasone of choosing media types nad link relations in the each resource call one by one with the clear explanation of its need
/User
GET,PUT,DELETE /user/{Id} : Two hypermedia link relations are provided to the API response including how to create a new user and how to delete a user with clear schema required for both of these operations. href link contains the resource url to make the request and all required parameters are alos mentioned in the API controls mumeta
/Users
GET,POST /users : create a new user and how to delete a user two hypermedia link relations are provided to the API response including with clear schema required for both of these operations. href link contains the resource url to make the request and all required parameters are alos mentioned in the API controls mumeta
/Video
GET,PUT,POST /video : Hypermedia links are provided to add a new video and all required schema and fileds are also included to be spefic about the call. Href contains the links of videos resource url to make a request
/videos
GET, POST /videos : Hypermedia links are provided to delete a video with video id and how to update a video with related schema, Href links contains the video resouce url to make a request
/Bookmark
POST, PUT /bookmark : get all videos and add video links are provided in the Example and reponses to facilitate the user in getting next videos or to add some specific video if user is admin too, Href links contains the url of videos resource to make a request with all required request body params and types
/Vote
POST /vote : Hypermedia links are provided to delete a video with video id and how to update a video with related schema, Href links contains the video resouce url to make a request
/Stats
GET /stats : Hypermedia links of getting all users and all videos are provided in the hypermeida part of the repsonse and Href contain the links of respective resources i.e. users, videos
/Authentication
POST /authentication : This returns only JWT token and that can be used by application user to make authenticated requests
Task | Student | Estimated time |
---|---|---|
State Machine Diagram and Hypermedia R&D | Muhammad Ahmed | 20 |
API Implementation and Documentation | Muhammad Talha Arshad | 20 |