Review of Payments BB API documentation

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

Structural problems:

• Gitbook

  • why in Service APIs, a table (that is unintelligible) is at the beginning if we have a list on the right?

  • descriptions of APIs without any actual endpoints should clearly state that the endpoint specifications are in progress, because it looks like that are missing (ex. 8.1.1)

  • schemas of endpoints besides having data type could have a description of parameter usage

  • some endpoints are added manually and some generated by swagger integration

• Github

  • multiple files that are unclear what they are

  • lots of json files while yaml was declared a standard

  • files are duplicated - why weren’t they overwritten but added as new entities?

  • endpoints have their separate files instead of being in the only one that should exist

    • /bulk-payment

    • /vouchers/voucher_preactivation

    • /vouchers/voucher_activation

    • /vouchers/voucher_redeemption

    • /vouchers/voucherstatuscheck/{voucherserialnumber}

    • /prepayment-validation

    • /prepayment-validation-response

    • /bills/{billId}

    • /transferRequests/{transferRequestId}

  • some files can’t be opened by Swagger due to the lack of parameters/wrong parsing

  • no Readme file to understand the content of the directory

Discrepancies and missing info:

• some parameters follow snake case and some camel case - it should be standardized

• endpoints in Github differ from the ones in Gitbook (some are present only in Github)

• in Gitbook some data is just not generated

API problems:

• POST /register-beneficiary

  • it’s only in Gitbook, no trace of it in Swagger

  • no required parameters?/ headers

• POST /update-beneficiary-details

  • it wasn’t generated successfully in Gitbook nor in Swagger

• POST /prepayment-validation

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

  • no error case presented (example and schema)

  • no headers

• POST /bulk-payment

  • no headers/ parameters

  • no error example

• POST https://virtserver.swaggerhub.com/VMS-API2/VMS-API2-GS_P_VMS_API-1.0.2/1.0.3/vouchers/voucher_preactivation

  • no required parameters?

  • in Gitbook schema of success response wasn’t generated successfully

• PATCH https://virtserver.swaggerhub.com/VMS-API2/VMS-API2-GS_P_VMS_API-1.0.2/1.0.3/vouchers/voucher_activation

  • no required parameters?

  • in Gitbook schema of success response wasn’t generated successfully

• POST https://virtserver.swaggerhub.com/VMS-API2/VMS-API2-GS_P_VMS_API-1.0.2/1.0.3/vouchers/voucher_redeemption

  • no required parameters?

  • in Gitbook schema of success response wasn’t generated successfully

• GET https://virtserver.swaggerhub.com/VMS-API2/VMS-API2-GS_P_VMS_API-1.0.2/1.0.3/vouchers/voucherstatuscheck/{voucherserialnumber}

  • in Gitbook schema of success response wasn’t generated successfully

• PATCH /vouchers/voucherstatuscheck/{voucherserialnumber}

  • not in Gitbook at all, only in Swagger

• GET /bills/{billId}

  • not in Gitbook at all

• GET /transferRequests/{transferRequestId}

  • not in Gitbook at all

Final conclusions:

• Readme file would greatly increase the readability of the directory (like in Consent BB)

• We need to stick with one standard for naming: either camel case or snake case

• Everything should be kept as clear as possible, user can’t search for information for hours, so we need to have just one file with endpoints in the repository

• Great to see so many examples of errors for different codes