RESTful API documentation and hypermedia - talha469/PWPProject GitHub Wiki

Important information for Deadline 4

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


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

SECTION GOALS:

  • Understand connectedness and/or hypermedia
  • Write API documentation

You have two options:

  1. 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
  2. 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.

RESTful API documentation

Resource relations

📑  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


OpenAI Logo


API Documentation

📑  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


Justification on Hypermedia Implementation

📑  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


Resources allocation

Task Student Estimated time
State Machine Diagram and Hypermedia R&D Muhammad Ahmed 20
API Implementation and Documentation Muhammad Talha Arshad 20
⚠️ **GitHub.com Fallback** ⚠️