Review of Identity BB API documentation

Owned by Aneta Pałczyńska (Deactivated)
Sep 26, 2023
2 min read

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

 

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