Misleading API endpoints regarding provisioning

[mayrmartin]

Description 😯

The API does expose a set of provisioning endpoints. There are several issues with these endpoints

provisioning.start

One would assume this endpoint does start the provisioning script of the provisioning service. But it does not - the endpoint sets a flag for the provisioning service indicating that the provision has started. Further, in case of an error, the endpoint does not return enough information. I.e. the system has already been provided by the provisioning script: one would assume the return status of the endpoint would not be HTTP 200 OK since provisioning the system multiple times by default is not permitted. Alternatively, 200 OK would be ok iif the message body of the response contains some additional information i.e. "failed to provision TruBudget - the system is already provisioned" with an additional status field indicating that the operation failed but not the request. In case of any error, the endpoint at the moment returns a message containing the API version & an empty data object.

provisioning.end

The assumption here (when looking at the name) is, the endpoint should stop provisioning but it checks a flag wheater the provisioing ended or not. It does not stop the provisioining. On error, the endpoint does not return a usefull information.

provisioned (this endpoint is defined wrong in the postman definition it is( provisioning.list but does not work 😉)

Why does this endpoint exist? One could simply call provisioning.end & get the information if provisioning ended or if there was an error.

Recomandation

• This fix is a breaking change. New endpoints should be provided & set as default for new releases (2.1 onwards). The existing endpoints should be marked as deprecated. With version 3.x the old legacy endpoints should be removed.
• If checking boolean values consider using the is keyword

Your Environment 🌎

API version 1.x and 2.x