Review of Identity BB API documentation

This is a review of the version 1.0 that was last modified 3 months ago.

Structural problems:

• Gitbook

  • some endpoints lack parameters or examples of request’s/response’s bodies

• Github

  • structural errors when the yaml file is opened in Swagger

Open

Discrepancies and missing info:

• all error messages should be shown as separete error codes, not come in a 200 response in an error parameter

• some endpoints use snake case and some camel case even for the same parameters (ex clientId vs client_id) - it should be standardized across the whole BB

API problems:

• POST /client-mgmt/oidc-client

  • no parameters/ headers?

  • error comes in 200 response - it should come as a separate error code

• PUT /client-mgmt/oidc-client/{client_id}

  • why PUT and not PATCH?

  • no headers?

  • error comes in 200 response - it should come as a separate error code

• GET /authorize

  • no example of 200 nor schema in Gitbook

  • no error examples

• POST /oauth/token

  • no headers/parameters?

• GET /oidc/userinfo

  • no example of a request

  • no parameters/headers?

  • no schema for error case

• GET /.well-known/jwks.json

  • no headers/parameters?

  • no error case

  • endpoint description says it should return jkws format, but content-type of the response is set to json

• GET /.well-known/openid-configuration

  • no headers/parameters?

  • no error case

• POST /linked-authorization/link-code

  • error comes in 200 response - it should come as a separate error code

• POST /linked-authorization/link-status

  • error comes in 200 response - it should come as a separate error code

• POST /linked-authorization/link-auth-code

  • error comes in 200 response - it should come as a separate error code

• POST /linked-authorization/link-transaction

  • no headers/parameters?

  • error comes in 200 response - it should come as a separate error code

• POST /linked-authorization/authenticate

  • no headers/parameters?

  • error comes in 200 response - it should come as a separate error code

• POST /linked-authorization/consent

  • no headers/parameters?

  • error comes in 200 response - it should come as a separate error code

• POST /wallet-binding

  • no headers/parameters?

  • error comes in 200 response - it should come as a separate error code

Final conclusions:

• Good readability - only one file in Github

• Preparing parameters descriptions would be helpful - either in repository or in schemas in Gitbook