Review of Messaging BB API documentation

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

Structural problems:

• Gitbook

  • all endpoints have missing or insufficient bodies of requests and responses

  • schemas of requests and responses are also missing

• Github 

  • bodies of a request should be described in the Request body section

    • Open

      

       

Discrepancies and missing info:

• Double naming standard for the parameters: sometimes parameter is written in snake case and sometimes in camel case

• In schemas purposes or details about parameters/keys would be beneficial for both clients and testing

• content-type is not specified for requests and responses

API problems:

• POST https://example.com/v1/send/email/single

  • no example or schema of the body in Gitbook (and Swagger)

  • no example of an error message

• POST https://example.com/v1/send/email/batch

  • example and schema of the body is not sufficient in Gitbook (and Swagger)

  • no example of an error message

• POST https://example.com/v1/callback/email

  • no example or schema of the body in Gitbook (and Swagger)

  • no example/schema of an error message

  • no example/schema of a success response

• GET https://example.com/v1/status/email

  • no example or schema of the body in Gitbook (and Swagger)

  • no example/schema of an error message

  • no example/schema of a success response - the one provided shows all statuses and not the example of one

Final conclusions:

• Great to have all endpoints in one file

• Readme file would add great descriptive value (like in Consent BB)

• Great to have an example of usage in the description of an endpoint