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.