add x-api-info-location header

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)
+- [Info Location Header](#info-location-header)
+  - [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)
@@ -113,6 +115,42 @@ X-Broker-API-Originating-Identity: kubernetes ew0KICAidXNlcm5hbWUiOiAiZHVrZSIsDQ
 ```
 
 
+## Info Location Header
+
+This header can be used by Platforms to provide Service Brokers with an endpoint
+that can be used to fetch information about the specific Platform deployment
+from which the request originated.
+
+The header consists of two parts: a `platform` string and `value` string,
+where the `value` is a Base64 encoded serialized JSON object.
+Both parts will vary based on the Platform which is being used. The
+following sections define the values to be used based on the Platform
+and which properties are expected to appear in the `value` JSON.
+
+### Cloud Foundry Info Location Header
+
+*`platform` Value*: `cloudfoundry`
+
+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-Broker-API-Originating-Identity: cloudfoundry ewogICJpbmZvX2xvY2F0aW9uX3VybCI6ICJodHRwczovL2FwaS5wbGF0Zm9ybS5leGFtcGxlLmNvbS92Mi9pbmZvIgp9
+```
+
+
 ## Context Object
 
 In the [Open Service Broker API specification](spec.md) there are certain

spec.md

@@ -154,6 +154,7 @@ The following HTTP Headers are defined for the operations detailed in this spec:
 | X-Broker-API-Version* | string | See [API Version Header](#api-version-header). |
 | X-Broker-API-Originating-Identity | string | See [Originating Identity](#originating-identity). |
 | X-Broker-API-Request-Identity | string | See [Request Identity](#request-identity). |
+| X-API-Info-Location | string | See [Info Location Header](profile.md#info-location-header). |
 
 \* Headers with an asterisk are REQUIRED.
 

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