Review of Information Mediator BB API documentation

This is a review of the version 1.0.1 that was last modified 2 months ago.

 

Structural problems:

  • Gitbook

    • there are almost no descriptions of endpoints and their purposes

    • there are almost no descriptions of parameters/keys to understand their purpose/details

  • Github 

    • too many files makes the API directory unclear

    • some endpoints like/listClients have separate files - all endpoints should be in one file

Discrepancies and missing info:

  • some parameters/keys are in camel case and some in snake case

  • error cases lack both examples and schemas

 

API problems:

 

 

 

 

Final conclusions:

  • It would be great to have all endpoints in one file

  • The chaos in API directory doesn't allow the user to understand what file is the right one

  • Readme file in API directory would greatly improve the readability

  • Parameters/keys descriptions (purposes and details) would help clients and the testing team