search

openservicebrokerapi / servicebroker

Open Service Broker API Specification
https://openservicebrokerapi.org/
Apache License 2.0
1.19k stars 434 forks source link

The Spec is unclear about what errors should look like. #403

Closed n3wscott closed 6 years ago

n3wscott commented 6 years ago

I think if the spec intends Error to be optionally returned for any error case it needs to be reworked. This is the language:

Service Brokers can include a user-facing message in the description field;

There is no spec language in that sentence, like MAY, and it is unclear is the broker author is allowed to return the description field for any responses or just for responses that call out they return errors.

The confusion happens when the spec says The expected response body is {}. This is redundant and unclear.

We should simplify errors to say they MAY always send error and description for all errors and remove the special cases for special errors.

mattmcneeney commented 6 years ago

I agree @n3wscott - anytime an API error occurs, brokers should be able to return the same error object. This is much more straightforward for platforms to understand.

I know we have the openapi changes for this in #389. We should make a sweeping change to spec.md too to clarify this if everyone agrees this is sensible.

fmui commented 6 years ago

This is related to #375.

mattmcneeney commented 6 years ago

Good spot @fmui. Although #375 looks like an extension to the spec (adding error codes) whereas this issue is regarding removing ambiguity.

mattmcneeney commented 6 years ago

This is going to be resolved by #409 so I'm closing this issue.