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:

• GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg//data/{registryname}/{versionnumber}

  • no error case (example+schema)

• PUT http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg//data/{registryname}/{versionnumber}/update

  • insufficient success response case (example+schema)

  • no error case (example+schema)

• POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg//data/{registryname}/{versionnumber}/update-or-create

  • no error case (example+schema)

• PUT http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg//data/{registryname}/{versionnumber}/update-entries

  • insufficient success response case (example+schema)

  • no error case (example+schema)

• GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg//data/{registryname}/{versionnumber}

  • no error case (example+schema)

• GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg//data/{registryname}/{versionnumber}/{uuid}/read-value/{field}.{ext}

  •  insufficient success response case (example+schema)

  • no error case (example+schema)

• POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg//data/{registryname}/{versionnumber}/exists

  • no error case (example+schema)

• DELETE http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg//data/{registryname}/{versionnumber}/{ID}/delete

  •  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)

• GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg//data/{registryname}/{versionnumber}

  • it’s duplicated

• POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg//data/{registryname}/{versionnumber}/read

  • 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