Reviews of API documentation

Owned by Aneta Pałczyńska (Deactivated)
Last updated: Oct 03, 2023
1 min read

BBs to review:
The one that SolDevelo prepared tests for:
BB Name (BB Lead)

  • Information Mediator

  • Messaging

  • Registration

  • Digital Registries

  • Payments

  • Identity

The one that SolDevelo didn’t prepared tests for:

  • Workflow

  • Consent

  • Scheduler

 

Common problems across API documentation:

  • Last update time differs between BBs - this means changes were made after the official publish date which should never happen

  • Not standardized naming conventions - camel case vs snake case vs kebab case vs pascal case

  • Schemas are missing in both success and error responses

  • Data in schemas are insufficiently described (in some cases they lack descriptions all together), besides having data type information they could also have a usage description

  • Differences between yaml files and Gitbook

  • Json files shouldn’t be present in api directory - agreed standard is yaml files

  • It’s recommedned in all of api directories to have Readme files

  • Endpoints should be in one yaml file, not in seperate ones

  • Changes to yaml files should overwrite the previous yaml file version - we shouldn’t upload a new ones when we introduce changes

  • Problems with generating endpoints if Gitbook was configured to display data automatically

  • Problem with endpoint names - we use whole urls, using just paths is recommended

  • Error responses should be described in the same manner as success responses

  • Error resposnes should use error codes, not be in 200 success repsosnes with separete parameter

  • All headers should be included in the endpoint description

  • All API documentation should follow the same pattern