Clarify HTTP Response code when the required service_id and plan_id are wrong

[dalv666]

What is the problem? Undefined HTTP Response code when the required service_id and plan_id are wrong (nonexistent) in

• Provisioning
• Binding
• Unbinding
• Deprovisioning

Who does this affect? This affects for service broker authors, platform authors and developers.

Do you have any proposed solutions? The closest code is - 400. But non existent service or plan is a logical error, not a syntax. 422 - has other meaning. 404 - possible solution

[mattmcneeney]

The Service Broker Errors section in the spec states:

When a request to a Service Broker fails, the Service Broker MUST return an appropriate HTTP response code. Where the specification defines the expected response code, that response code MUST be used.

However, I agree that in this case the text describing 400 Bad Request does not seem to include this scenario:

400 Bad Request: MUST be returned if the request is malformed or missing mandatory data.

What about changing that text to:

400 Bad Request: MUST be returned if the request is malformed, missing mandatory data or contains invalid data.

What do you think @dalv666 ? I know this may technically be a breaking change and so we may have to put this new scenario in a MAY rather than a MUST.

[waterlink]

@mattmcneeney @dalv666

That sounds like an excellent description of 400 Bad Request looking at it from my RESTful and HTTP APIs development experience:

400 Bad Request: MUST be returned if the request is malformed, missing mandatory data or contains invalid data.

MUST/MAY version:

400 Bad Request: MUST be returned if the request is malformed or missing mandatory data; MAY be returned if the request contains invalid data.

Also, we have a lot of duplicated descriptions of 400 Bad Request all over the spec. They all will have to be updated. (Do you see any way we can de-duplicate this?)

Additionally, there must be a proper error description stating which fields are invalid and in what way, so that the platform developer (or user if error bubbles up) can understand what happened and take appropriate action. So some line like this might also be needed:

If Service Broker returns 400 Bad Request when the request contains invalid data, it MUST indicate in the description which fields are invalid and in what way.

(feel free to improve my wording on that one)

[dalv666]

@mattmcneeney @waterlink

Nice, 400 Bad Request is acceptable.

MUST/MAY version is most loyal specification change:

400 Bad Request: MUST be returned if the request is malformed or missing mandatory data; MAY be returned if the request contains invalid data.

It is unnecessary to delete duplicates:

• easy to read possible error codes for each type of request
• specification may change

And yes, it needs to be said:

If Service Broker returns 400 Bad Request when the request contains invalid data, it MUST indicate in the description which fields are invalid and in what way.

[mattmcneeney]

Great, thanks @dalv666. PR incoming - let me know what you think!