Review of Registration BB API documentation

This is a review of the version 1.0 that was last modified 1 month ago.

Structural problems:

• Gitbook

  • some endpoints are duplicated (ex. http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg/api//services/{serviceId} or http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg/api//services/{serviceId}/eForms)

  • many endpoints can be accessed by both, the user and an operator and thus they are duplicated - we could describe them more using usage flows or have just one instance of an endpoint and write that both actors can access it

• Github

  • Endpoints file should be a yaml, not a json

Discrepancies and missing info:

• In schemas purposes or details about parameters/keys could be more detailed for both the clients and testing

• Content-type is not specified for all of the responses

API problems:

• GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg/api//services

  • no headers

  • lack of content-type for error response

• GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg/api//services/{serviceId}

  • no headers

  • lack of content-type for error response

  • one error response lacks example and schema

  • it’s duplicated

• GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg/api//services/{serviceId}/eForms

  • no headers

  • no error responses

  • it’s duplicated

• GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg/api//eForms/{eFormId}

  • no headers

  • no error response example and schema

• POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg/api//services/{serviceId}/applications

  • request body’s schema was not generated successfully

  • success response body’s schema was not generated successfully

  • one error response lacks example and schema

  • lack of content-type for success and error responses

  • it’s duplicated

• POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg/api//documents

  • no headers

  • no required parameters?

  • request body’s schema was not generated successfully

  • lack of content-type for success and error responses

  • it’s duplicated

• GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg/api//applications

  • lack of content-type for success response

  • no error responses

  • it’s duplicated

• GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg/api//applications/{fileId}

  • success response body’s schema was not generated successfully

  • no headers

  • error response lacks example and schema

  • lack of content-type for success response

  • it’s duplicated

• GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg/api//tasks

  • no headers

  • lack of content-type for success response

  • no error responses

  • it’s duplicated

• GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg/api//tasks/{taskId}

  • no headers

  • no error responses

  • lack of content-type for success response

  • it’s duplicated

• PUT http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg/api//applications/{fileId}

  • request body’s schema was not generated successfully

  • success response body’s schema was not generated successfully

  • one error response lacks example and schema

  • lack of content-type for responses

• POST http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg/api//tasks/{taskId}/complete

  • no headers

  • one error response lacks example and schema

  • lack of content-type for responses

• GET http://ss2.egovstack.net/r1/eGovStack/COM/11222456/RegistrationBB/creg//data/statistics/1.0

  • error responses lack examples and schemas

Final conclusions:

• Great to have a Readme file - but it should be updated

• UMLs are a great addition

• Endpoints file should be a yaml file, not a json

• All parameters follow a common naming convention which is great