Customize Responses

Response formats

There are three responses formats to choose from when generating SDKs. These control the shape of response types in supported languages.

To configure the response format, edit your gen.yaml file for a given target:


typescript:  # Python and Go can be configured in a similar way
  responseFormat: flat  # Or envelope-http, or envelope
  packageName: @acme/super-sdk
  version: 0.1.0
  author: Speakeasy
  templateVersion: v2
  clientServerStatusCodesAsErrors: true
  maxMethodParams: 4
  flattenGlobalSecurity: true
  inputModelSuffix: input
  outputModelSuffix: output
  additionalDependencies:
    dependencies: {}
    devDependencies: {}
    peerDependencies: {}
  imports:
    option: openapi
    paths:
      callbacks: models/callbacks
      errors: models/errors
      operations: models/operations
      shared: models/components
      webhooks: models/webhooks

In the following sections, the following specification will be used as a reference:


  /payments/{id}:
    get:
      operationId: getPayment
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Details about a payment
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Payment"
components:
  schemas:
    Payment:
      type: object
      required: [id,amount,currency]
      properties:
        id:
          type: integer
        amount:
          type: number
        currency:
          type: string

`responseFormat: flat`

The flat response format is the simplest form and most ergonomic since there is no wrapper type generated and SDK users get direct access to the response value:

When enabled, the generated SDK code will return the Payment type directly with no indirection:


export class SDK extends ClientSDK {
  async getPayment(id: string, options?: RequestOptions): Promise<components.Payment> {}
}

If users want to debug HTTP metadata then a custom client can be passed to the SDK instance.

`responseFormat: envelope-http`

This format builds response types with a wrapper that holds the response value and associated HTTP metadata.

When enabled, the generated SDK code will produce the response types below:


class SDK extends ClientSDK {
    async getPayment(id: string, options?: RequestOptions): Promise<operations.GetPaymentResponse> {}
}


export type GetPaymentResponse = {
    httpMeta: components.HTTPMetadata;
    /**
     * Details about a payment
     */
    payment?: components.Payment | undefined;
};


export type HTTPMetadata = {
  /**
   * Raw HTTP response; suitable for custom response parsing
   */
  response: Response;
  /**
   * Raw HTTP request; suitable for debugging
   */
  request: Request;
};

The built-in HTTP metadata will also appear in any custom or built-in error types that are thrown or returned from the SDK.

This format contains the most details about the underlying HTTP requests with the trade-off of introducing indirection in the form of a wrapper value.

`responseFormat: envelope`

This format builds response types with a wrapper that holds the response value and minimal information about the underlying HTTP response.

It is recommended to use envelope-http instead of envelope since it contains a more complete view of the HTTP request and response.

When enabled, the generated SDK code will produce the response types below:


class SDK extends ClientSDK {
    async getPayment(id: string, options?: RequestOptions): Promise<operations.GetPaymentResponse> {}
}


export type GetPaymentResponse = {
  /**
   * HTTP response content type for this operation
   */
  contentType: string;
  /**
   * HTTP response status code for this operation
   */
  statusCode: number;
  /**
   * Raw HTTP response; suitable for custom response parsing
   */
  rawResponse: Response;
  /**
   * Details about a payment
   */
  payment?: components.Payment | undefined;
};