Review of Digital Registries BB API documentation
This is a review of the version 1.0 that was last modified 4 months ago.
Structural problems:
Gitbook
there could be more descriptions of parameters/keys to understand their purpose/details
two endpoints are duplicated (/data/{registryname}/{versionnumber}/read and /data/{registryname}/{versionnumber})
Github
too many files makes the API directory unclear
in Readme file it is stated that the standard is json, but it should be yaml
json files could be removed
/data/{registryname}/{versionnumber}/create
is in Swagger but not in Gitbook
Discrepancies and missing info:
some parameters follow snake case and some camel case - it should be standardized [PR #54]
some endpoints are duplicated
one endpoint is only in Swagger
almost no error responses are described
API problems:
no error case (example+schema)
insufficient success response case (example+schema)
no error case (example+schema)
no error case (example+schema)
insufficient success response case (example+schema)
no error case (example+schema)
no error case (example+schema)
insufficient success response case (example+schema)
no error case (example+schema)
no error case (example+schema)
insufficient success response case (example+schema)
no error case (example+schema)
GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg//data/MyPersonalDataUsage/1.0
no error cases (example+schema)
GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/swaggerhub/creg//database/{id}
no error cases (example+schema)
POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/swaggerhub/creg//database/modify
why updating is not done by PATCH or even PUT?
no error cases (example+schema)
DELETE http://ss2.egovstack.net/r1/eGovStack/COM/11222456/swaggerhub/creg//database/{id}
insufficient success response case (example+schema)
no error case (example+schema)
GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/swaggerhub/creg//databases
no error case (example+schema)
POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg//data/mcts/1.4/create-entries
it’s only in Gitbook, not in Swagger
no error case (example+schema)
it’s duplicated
it’s duplicated
POST
/data/{registryname}/{versionnumber}/create
it’s only in Swagger, not in Gitbook
no error case (example+schema)
Final conclusions:
Readme file should be updated
Files in API directory should be minimized (all endpoints should be in one file)
Parameters/keys in schemas could be better described (purpose/details)
Error responses should be added