IPA-115: Envelope Object

Some clients might not be able to access the HTTP response headers and/or status code. In that case, clients can request that the response include an "envelope," which is simply an extra layer of information in the JSON document and contains any relevant details that would normally be in the response headers.

Guidance

1. Resources may support a boolean envelope query parameter.

2. envelope must default to false.

   parameters:
     - name: envelope
       in: query
       schema:
         type: boolean
         default: false

   Why:

   The envelope parameter declares default: false, so a client that omits it receives the unwrapped response.

3. If envelope is set to true for individual resources, the response must include the field status as the HTTP status code and the field content as the requested resource.

   {
     "status": 200,
     "content": {
       "id": "5f1b...",
       "name": "Cluster0"
     }
   }

   Why:

   With envelope=true, the response wraps the requested resource under content and surfaces the HTTP status code under status, so a client that cannot read response headers still has both.

   1. Call the individual resource operation with envelope=true.

   2. Confirm the response body includes a status field carrying the HTTP status code.

   3. Confirm the requested resource is nested under the content field.

4. If envelope is set to true for Paginated resources the existing response must include the field status as the HTTP status code.

   {
     "status": 200,
     "results": [],
     "totalCount": 0
   }

   Why:

   For a paginated resource, the existing response shape is preserved and only a status field is added carrying the HTTP status code, so the envelope does not reshape the pagination response.

   1. Call the paginated resource operation with envelope=true.

   2. Confirm the existing paginated response body is preserved and a status field carrying the HTTP status code is added.

Generated API Clients

1. Generated clients must not support envelope.

   • Conditionally changing the shape of a response is not supported by code generation tools

   Why:

   Generated clients expect a single, stable response shape per operation. Because the envelope conditionally changes that shape, code generation tools cannot represent it, so generated clients must not support envelope.

   1. Identify which clients are produced by code generation tools.

   2. Confirm those generated clients do not expose or set the envelope parameter, since it conditionally changes the response shape.