I have a question of how to handle API Version Header of service broker
(X-Broker-Api-Version) in http request header.

First of all, I found the CF manual mentioned as follows;
===
This header will be useful in future minor revisions of the API to allow
brokers to reject requests from Cloud Controllers that they do not
understand.
===

In addition, spring-boot-cf-service-broker, which is one of reference
implementations for service brokers, seems to verify if the
X-Broker-Api-Version value is exactly equal to the expected API for each
request it receives by default.

Does the CF community recommend that service broker should reject any
requests from CC if X-Broker-Api-Version value is not equal to the API
version which it expects?

- X-Broker-Api-Version = 2.5
- API version for a service broker to understand =2.4

If so, personally this policy does not make sence to me because it will
cause frequent modifications of service brokers whenever CF version is
updated. I prefer the service broker accepts requests from CC which exposes
the newer X-Broker-Api-Versions it understand so that it can work with the
latest CF without code modifications.



--
View this message in context: http://cf-dev.70369.x6.nabble.com/Message-Broker-Version-Verification-tp428.html
Sent from the CF Dev mailing list archive at Nabble.com.

Hello Masumi,

I tend to agree with you and am in favor of updating the description of
this field to be more generalized. Cloud Foundry includes the
X-Broker-Api-Version
for informational purposes. I don't expect a broker author to reject
requests just because the value of this header is less than or greater than
X. I expect broker authors will reject unsupported requests; in some cases
we provide mechanisms for a broker to signal to CF that an endpoint isn't
supported.

Examples:
- Since v2.0 we've supported the PUT
/v2/service_instances/:guid/service_bindings/:guid endpoint. A broker that
hasn't implemented this endpoint might return a 404. But a broker can also
return 'bindable: false' in their catalog which prevents CF from calling
the endpoint at all.
- In v2.4 we introduced the PATCH /v2/service_instances endpoint. A broker
that hasn't implemented the endpoint might return a 404. But a broker can
return 'plan_updateable: false' to prevent CC from calling the endpoint
when a user attempts to change their plan, or 422 if a particular plan
change isn't supported. We're adding support for arbitrary parameters on
the update endpoint also, and brokers will be responsible for validation.

So rather than rejecting calls based on the version, it seems to me that
broker authors are more likely to handle validation on a case-by-case (or
feature-by-feature) basis.

Shannon Coen
Product Manager, Cloud Foundry
Pivotal, Inc.