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:

• GET https://SECURITYSERVER/r1/listClients

  • no required parameters?

  • no headers

  • no request example

  • no error case (example+schema)

• GET https://SECURITYSERVER/r1/govstack/GOV/ministry-of-things/thing-hub/listMethods

  • no required parameters?

  • no request example

  • no error case (example+schema)

• GET https://SECURITYSERVER/r1/govstack/GOV/ministry-of-things/thing-hub/allowedMethods

  • no required parameters?

  • no request example

  • no error case (example+schema)

• GET https://SECURITYSERVER/r1/govstack/GOV/ministry-of-things/thing-hub/getOpenAPI

  • no required parameters?

  • no request example

  • no error case (example+schema)

  • insufficient success case (example+schema)

• GET https://SECURITYSERVER/r1/govstack/GOV/ministry/room/subs

  • no required parameters?

  • no request example

  • no error case (example+schema)

• POST https://SECURITYSERVER/r1/govstack/GOV/ministry/room/subs

  • no required parameters?

  • insufficient examples of responses

  • no content-type for responses

• GET https://SECURITYSERVER/r1/govstack/GOV/ministry/room/subs/{id}

  • no error case

• DELETE https://SECURITYSERVER/r1/govstack/GOV/ministry/room/subs/{id}

  • no error case (example+schema)

  • no success case (example+schema)

• PATCH https://SECURITYSERVER/r1/govstack/GOV/ministry/room/subs/{id}

  • no error case (example+schema)

  • no success case (example+schema)

• GET https://SECURITYSERVER/r1/govstack/GOV/ministry/room/pull/{serviceCode}/{operationId}

  • no examples and schemas of error responses

  • success schema was not generated successfully

• GET https://SECURITYSERVER/r1/govstack/GOV/ministry/room/pull/{serviceCode}/{operationId}/{eventId}

  • no examples and schemas of error responses

  • success schema was not generated successfully

• DELETE https://SECURITYSERVER/r1/govstack/GOV/ministry/room/pull/{serviceCode}/{operationId}/{eventId}

  • no examples and schemas of error responses

  • no success case (example+schema)

• GET https://SECURITYSERVER/r1/govstack/GOV/ministry/room/event/{id}

  • no examples and schemas of error response

  • success schema was not generated successfully

• DELETE https://SECURITYSERVER/r1/govstack/GOV/ministry/room/event/{id}

  • no examples and schemas of error response

  • no success case (example+schema)

• GET https://SECURITYSERVER/r1/{GovStackInstance}/{memberClass}/{memberCode}/{applicationCode}/getOpenAPI

  • no such endpoint in Swagger

  • seems identical to https://SECURITYSERVER/r1/govstack/GOV/ministry-of-things/thing-hub/getOpenAPI

  • insufficient example and schema of a success response

  • no examples and schemas of error responses

• GET https://SECURITYSERVER:/api/v1/config

  • no parameters/headers

  • no error responses

• POST https://SECURITYSERVER:/api/v1/config

  • no headers

  • insufficient example and schema of a success response

  • no examples and schemas of error responses

• PUT https://SECURITYSERVER:/api/v1/config

  • no headers/parameters

  • insufficient example and schema of a success response

  • no examples and schemas of error responses

• PATCH https://SECURITYSERVER:/api/v1/config

  • no headers/parameters

  • insufficient example and schema of a success response

  • no examples and schemas of error responses

• GET https://SECURITYSERVER:/api/v1/status

  • no headers/parameters

  • insufficient example and schema of a success response

  • no examples and schemas of error responses

• GET https://SECURITYSERVER:/api/v1/rights/allow

  • no headers?

  • no examples and schemas of error responses

• PATCH https://SECURITYSERVER:/api/v1/rights/allow

  • no headers/parameters?

  • insufficient example and schema of a success response

  • no examples and schemas of error responses

• PATCH https://SECURITYSERVER:/api/v1/rights/deny

  • no headers/parameters

  • insufficient example and schema of a success response

  • no examples and schemas of error responses

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