Review of Consent BB API documentation

This is a review of the version that is still under development (but was supposed to be published on the 18th of September 2023).

Structural problems:

• Gitbook

  • some endpoints weren’t generated from Swagger and “Oops, something is missing” panels are shown

  • some bodies of both requests and responses are missing

  • no error examples were provided, but should include not only the error code but also an error message and content-type

  • some endpoints that were listed in Gitbook aren’t in Swagger (and are not generated correctly in Gitbook)

• Github

  • no problems

Discrepancies and missing info:

• some endpoints have an example of success 200 and some don’t (even if only status is returned, it’s recommended to have an example of a response including success message) ex. https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/{policyId}/revisions/ vs https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/

• in endpoint response/request schemas, some examples of key/parameter values are not provided

• not all data is generated correctly from Swagger as it differs from one another

API problems:

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/

  • no headers/parameters

  • no example of an error response

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/{policyId}/

  • no headers/parameters

  • no example of an error

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/{policyId}/revisions/

  • no headers/parameters

  • no example of an error

• PUT https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/{policyId}/

  • no Gitbook info was generated

  • no headers/parameters

  • no request example

  • why put and not patch?

  • no example of an error

• DELETE https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policy/{policyId}/

  • no Gitbook info was generated

  • no headers/parameters

  • no request example

  • no example of an error

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/policies/

  • no headers/parameters

  • no example of an error

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/agreement/{agreementId}/

  • no headers/parameters

  • no example of an error

• PUT https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/agreement/{agreementId}/

  • no request example

  • no headers/parameters

  • no example of an error

• DELETE https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/agreement/{agreementId}/

  • no request example

  • no headers/parameters

  • no example of an error

• POST https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/agreement/

  • no request example in Gitbook

  • no headers/parameters

  • no example of an error

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//config/agreements/

  • no headers/parameters

  • no example of an error

• POST /config/agreements/

  • it’s missing from Gitbook at all

  • no headers/parameters

  • no example of an error

• POST https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/

  • no headers/parameters

  • no example of an error

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/{individualId}/

  • no headers/parameters

  • no example of an error

• PUT https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/{individualId}/

  • why PUT and not PATCH?

  • no headers/parameters

  • no example of an error

• DELETE https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/{individualId}/

  • no headers/parameters

  • no request example

  • no example of an error

  • is the 200 response ok?

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individuals/

  • no headers/parameters

  • no example of an error

  • is the 200 response ok?

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/agreement/{agreementId}/

  • in Gitbook we are missing the response body example that is in Swagger

  • no headers/parameters

  • no example of an error

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/policy/{policyId}/

  • in Gitbook we are missing the response body example that is in Swagger

  • no headers/parameters

  • no example of an error

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/purpose/{purposeId}/

  • in Gitbook we are missing the response body example that is in Swagger

  • no headers/parameters

  • no example of an error

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/agreement/{agreementId}/agreementdata/

  • in Gitbook we are missing the response body example that is in Swagger

  • no headers/parameters

  • no example of an error

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/verification/agreements/

  • in Gitbook we are missing the response body example that is in Swagger

  • no headers/parameters

  • no example of an error

• POST /service/verification/agreements/

  • it’s missing entirely from Gitbook but is in the Swagger

  • no headers/parameters

  • no example of an error

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/verification/agreement/{agreementId}/

  • in Gitbook we are missing the response body example that is in Swagger

  • no headers/parameters

  • no example of an error

• POST /service/verification/consentrecords/

  • it wasn’t generated successfully in Gitbook, it’s only visible in Swagger

  • no headers/parameters

  • no example of an error

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/record/agreement/{agreementId}/

  • in Gitbook we are missing the response body example that is in Swagger

  • no headers/parameters

  • no example of an error

• POST https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/record/agreement/{agreementId}/

  • in Gitbook we are missing the response body example that is in Swagger

  • no example of request body

  • no headers/parameters

  • no example of an error

• POST https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/record/consentrecord/draft/

  • in Gitbook we are missing the response body example that is in Swagger

  • no example of request body

  • no headers/parameters

  • no example of an error

• POST https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/record/consentrecord/

  • no required parameters?

  • in Gitbook we are missing both request and response bodies

  • no headers/parameters

  • no example of an error

• PUT https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/record/consentrecord/{consentRecordId}/

  • no body of a request

  • why PUT and not PATCH?

  • no headers/parameters

  • no example of an error

  • missing response body in Gitbook, but is in swagger

• POST https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/record/consentrecord/{consentRecordId}/signature/

  • no body of a request

  • no headers/parameters

  • no example of an error

  • missing response body in Gitbook, but is in swagger

• PUT https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/record/consentrecord/{consentRecordId}/signature/

  • why PUT and not PATCH?

  • no headers/parameters

  • no example of an error

• GET /service/individual/record/agreement

  • no such endpoint is in Swagger, but it’s in the endpoints list in Gitbook

  • the endpoint is not generated correctly with a message “Oops, something is missing”

• GET /service/individual/record/agreement/{agreementId}/all/

  • it’s in the Swagger but not in Gitbook

  • no headers/parameters

  • no example of an error

• GET /service/individual/record/

  • it’s in the Swagger but not in Gitbook

  • no headers/parameters

  • no example of an error

  • no required parameters?

• DELETE https://app.swaggerhub.com/apis/GovStack/consent-management-bb//service/individual/record/

  • no headers/parameters

  • no example of an error

  • no request nor response bodies

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//audit/trackers/

  • no headers/parameters

  • no example of an error

  • no required parameters?

• POST https://app.swaggerhub.com/apis/GovStack/consent-management-bb//audit/tracker/

  • no headers/parameters

  • no example of an error

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//audit/tracker/{trackerId}/

  • no headers/parameters

  • no example of an error

• PUT https://app.swaggerhub.com/apis/GovStack/consent-management-bb//audit/tracker/{trackerId}/

  • no headers/parameters

  • no example of an error

  • why PUT not PATCH?

• DELETE https://app.swaggerhub.com/apis/GovStack/consent-management-bb//audit/tracker/{trackerId}/

  • no headers/parameters

  • no example of an error

  • no request body

• GET /audit/consentrecords/

  • no such endpoint is in Swagger, but it’s in the endpoints list in Gitbook

  • the endpoint is not generated correctly with a message “Oops, something is missing”

• POST /audit/consentrecords/

  • no such endpoint in Gitbook, but it’s in the Swagger

  • no required parameters?

  • no headers

  • no example of an error

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//audit/consentrecord/{consentRecordId}/

  • no headers

  • no example of an error

  • missing response body in Gitbook, but is in swagger

• GET /audit/agreements/

  • no such endpoint is in Swagger, but it’s in the endpoints list in Gitbook

  • the endpoint is not generated correctly with a message “Oops, something is missing”

• POST audit/agreements/

  • no such endpoint in Gitbook, but it’s in the Swagger

  • no required parameters?

  • no headers

  • no example of an error

• GET https://app.swaggerhub.com/apis/GovStack/consent-management-bb//audit/agreement/{agreementId}/

  • no headers

  • no example of an error

  • double slash in endpoint path

  • missing response body in Gitbook, but is in swagger

• GET /status/startup/

  • no such endpoint in Gitbook, but it’s in the Swagger

  • no parameters at all

  • no headers

  • no example of an error

  • no example of a request nor response bodies

• GET /status/readiness/

  • no such endpoint in Gitbook, but it’s in the Swagger

  • no parameters at all

  • no headers

  • no example of an error

  • no example of a request nor response bodies

Final conclusions:

• In Github, a Readme file is a great addition

• In Github, CSVs with the data schema and endpoints details is a great addition, makes everything clear and understandable for non-technical stakeholders

• The API was still not published and there are some endpoints with DRAFT label