Review of Scheduler BB API documentation

This is a review of the version 1.0.1 that was last modified less than 1 month ago.

 

Structural problems:

  • Gitbook

    • In all of the schemas there aren’t any parameters descriptions - only their data types

    • “default” response is present in all endpoints, but we should only have success and error responses (and text of a deafult response indicated it’s for errors?)

    • Why responses are objects inside arrays that are inside arrays? There are no parameters in etiher the first array or the second array, object is their only child.

  • Github

    • Empty test.txt file is unnecessary

    • Endpoints should be in yaml file, not json file

Discrepancies and missing info:

  • Bodies of requests aren’t in snippets of code (example/schema view), but success responses are. Both Requests and responses should have examples and schemas in snippets of code for readability

  • All responses should follow content-type “application/json” but sometimes it’s only “json”

  • Why reponses are described as content-type json, bu in examples are presented as simple strings? They should ba a json with an only parameter that is a string.

API problems:

 

 

 

 

 

 

 

 

Final conclusions:

  • It would be great to have a Readme file

  • All parameters follow a common naming convention which is great

  • In schemas we should not only state the data type of a parameter but also describe their details and purpose

  • We should follow the standard of having a body of a request in code snippets

  •