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