add x-api-info-location header to profile

Author: Matt McNeeney

openapi.yaml

@@ -49,6 +49,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/APIVersion'
         - $ref: '#/components/parameters/OriginatingIdentity'
+        - $ref: '#/components/parameters/InfoLocation'
         - name: instance_id
           in: path
           description: instance id of instance to provision
@@ -112,6 +113,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/APIVersion'
         - $ref: '#/components/parameters/OriginatingIdentity'
+        - $ref: '#/components/parameters/InfoLocation'
         - name: instance_id
           in: path
           description: instance id of instance to update
@@ -163,6 +165,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/APIVersion'
         - $ref: '#/components/parameters/OriginatingIdentity'
+        - $ref: '#/components/parameters/InfoLocation'
         - name: instance_id
           in: path
           description: id of instance being deleted
@@ -225,6 +228,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/APIVersion'
         - $ref: '#/components/parameters/OriginatingIdentity'
+        - $ref: '#/components/parameters/InfoLocation'
         - name: instance_id
           in: path
           description: instance id of instance to fetch
@@ -370,6 +374,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/APIVersion'
         - $ref: '#/components/parameters/OriginatingIdentity'
+        - $ref: '#/components/parameters/InfoLocation'
         - name: instance_id
           in: path
           description: instance id of instance to create a binding on
@@ -439,6 +444,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/APIVersion'
         - $ref: '#/components/parameters/OriginatingIdentity'
+        - $ref: '#/components/parameters/InfoLocation'
         - name: instance_id
           in: path
           description: id of the instance associated with the binding being deleted
@@ -501,6 +507,7 @@ paths:
       parameters:
         - $ref: '#/components/parameters/APIVersion'
         - $ref: '#/components/parameters/OriginatingIdentity'
+        - $ref: '#/components/parameters/InfoLocation'
         - name: instance_id
           in: path
           description: instance id of instance associated with the binding
@@ -545,6 +552,13 @@ components:
       schema:
         type: string
 
+    InfoLocation:
+      name: X-Api-Info-Location
+      in: header
+      description: endpoint for fetching additional information about the Platform
+      schema:
+        type: string
+
   schemas:
     Catalog:
       type: object

profile.md

@@ -15,6 +15,8 @@ or REQUIRED level requirements defined herein.
 - [Notations and Terminology](#notations-and-terminology)
   - [Notational Conventions](#notational-conventions)
   - [Terminology](#terminology)
+- [Additional Headers](#additional-headers)
+  - [Cloud Foundry Info Location Header](#cloud-foundry-info-location-header)
 - [Originating Identity Header](#originating-identity-header)
   - [Cloud Foundry Originating Identity Header](#cloud-foundry-originating-identity-header)
   - [Kubernetes Originating Identity Header](#kubernetes-originating-identity-header)
@@ -42,6 +44,38 @@ be interpreted as described in [RFC 2119]( https://tools.ietf.org/html/rfc2119).
 Please refer to terminology defined by the
 [Open Service Broker API specification](spec.md#terminology).
 
+
+## Additional Headers
+
+### Cloud Foundry Info Location Header
+
+The `X-API-Info-Location` header is used to provide Service Brokers with an
+endpoint that can be used to fetch information about the specific Cloud Foundry
+deployment from which the request originated.
+
+The header consists of a `value` string, where the `value` is a Base64 encoded
+serialized JSON object.
+
+The following properties MUST appear within the JSON encoded `value`:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| info_location_url | string | The URL of an endpoint that can be used to fetch information about the Cloud Foundry deployment from which the request originated. |
+
+Platforms MAY include additional properties.
+
+For example, a `value` of:
+```json
+{
+  "info_location_url": "https://api.platform.example.com/v2/info"
+}
+```
+would appear in the HTTP Header as:
+```
+X-API-Info-Location: ewogICJpbmZvX2xvY2F0aW9uX3VybCI6ICJodHRwczovL2FwaS5wbGF0Zm9ybS5leGFtcGxlLmNvbS92Mi9pbmZvIgp9
+```
+
+
 ## Originating Identity Header
 
 In the [Open Service Broker API specification](spec.md) it defines an

spec.md

@@ -157,6 +157,9 @@ The following HTTP Headers are defined for the operations detailed in this spec:
 
 \* Headers with an asterisk are REQUIRED.
 
+Additional headers for specific Platforms are detailed in the
+[profile](profile.md#additional-headers) document.
+
 ### API Version Header
 
 Requests from the Platform to the Service Broker MUST contain a header that

swagger.yaml

@@ -35,6 +35,7 @@ paths:
       - $ref: '#/parameters/APIVersion'
       - $ref: '#/parameters/OriginatingIdentity'
       - $ref: '#/parameters/RequestIdentity'
+      - $ref: '#/parameters/InfoLocation'
     get:
       summary: get the catalog of services that the service broker offers
       tags:
@@ -56,6 +57,7 @@ paths:
       - $ref: '#/parameters/APIVersion'
       - $ref: '#/parameters/OriginatingIdentity'
       - $ref: '#/parameters/RequestIdentity'
+      - $ref: '#/parameters/InfoLocation'
       - name: instance_id
         in: path
         description: instance id of instance to provision
@@ -184,6 +186,7 @@ paths:
       - $ref: '#/parameters/APIVersion'
       - $ref: '#/parameters/OriginatingIdentity'
       - $ref: '#/parameters/RequestIdentity'
+      - $ref: '#/parameters/InfoLocation'
       - name: instance_id
         in: path
         description: instance id of instance to provision
@@ -231,6 +234,7 @@ paths:
       - $ref: '#/parameters/APIVersion'
       - $ref: '#/parameters/OriginatingIdentity'
       - $ref: '#/parameters/RequestIdentity'
+      - $ref: '#/parameters/InfoLocation'
       - name: instance_id
         in: path
         description: instance id of instance to provision
@@ -283,6 +287,7 @@ paths:
       - $ref: '#/parameters/APIVersion'
       - $ref: '#/parameters/OriginatingIdentity'
       - $ref: '#/parameters/RequestIdentity'
+      - $ref: '#/parameters/InfoLocation'
       - name: instance_id
         in: path
         description: instance id of instance to provision
@@ -399,6 +404,11 @@ parameters:
     in: header
     description: idenity of the request from the Platform
     type: string
+  InfoLocation:
+    name: X-Api-Info-Location
+    in: header
+    description: endpoint for fetching additional information about the Platform
+    type: string
   accepts_incomplete:
     name: accepts_incomplete
     in: query