Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

x-yc-apigateway-integration:http extension

Written by
Updated at April 24, 2025

The x-yc-apigateway-integration:http extension redirects a request to the relevant URL.

You can add an extension to a specification using the specification constructor.

Supported parameters

The table below lists the parameters specific to API Gateway API gateways. You can find the description of other parameters in the OpenAPI 3.0 specification.

Parameter Type Description
url string URL to redirect the invocation to. It must be accessible from the internet or the user network specified in the API gateway settings.
The parameters are subsituted into url.
method enum This is an optional parameter. It sets the HTTP method for invocation. If it is not specified, the method to send a request to API Gateway will be used.
headers map[string](string | string[]) HTTP headers to provide. By default, headers of the original request are not provided.
The parameters are subsituted into headers.
query map[string](string | string[]) Query parameters to provide. By default, query parameters of the original request are not provided.
The parameters are subsituted into query.
timeouts object read and connect invocation timeouts. The value is specified in seconds and must not exceed the set limit. This is an optional parameter. If no value is specified, HTTP requests will be aborted after the timeout specified for the API gateway.
omitEmptyHeaders boolean This is an optional parameter. If set to true, empty headers are not provided.
omitEmptyQueryParameters boolean This is an optional parameter. If set to true, empty query parameters are not provided.
serviceAccountId string Service account ID. It is used for authorization when accessing the specified URL. The serviceAccountId top-level parameter value is ignored.

Extension specification

Specification example:

x-yc-apigateway-integration:
  type: http
  url: https://example.com/backend1
  method: POST
  headers:
    Authorization: Basic ZjTqBB3f$IF9gdYAGlMrs2********
  query:
    my_param: myInfo
  timeouts:
    connect: 0.5
    read: 5

Extension features:

  • If the value of a header or query parameter is an array, it is provided as a single string separated by commas.
  • By default, headers other than User-Agent and query parameters of the original request are not provided. To provide all the original request's headers and query parameters that are not overridden in the specification, add the string containing '*': '*' to the query and headers sections. To leave out some headers, give them empty values and set the omitEmptyHeaders field to true. Similarly, you can leave out some query parameters by using the omitEmptyQueryParameters field.
  • The User-Agent header is provided by default unless it is overridden in the specification.
  • To redirect all requests, use greedy parameters and the generic HTTP method.

Here is an example of proxying all requests to https://example.com, where the Content-Type header and the param query parameter are provided:

openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /{path+}:
    x-yc-apigateway-any-method:
      x-yc-apigateway-integration:
        type: http
        url: https://example.com/{path}
        headers:
          Content-Type: '{Content-Type}'
        query:
          param: '{param}'
        timeouts:
          connect: 0.5
          read: 5
      parameters:
      - name: Content-Type
        in: header
        required: false
        schema:
          type: string
      - name: path
        in: path
        required: false
        schema:
          type: string
      - name: param
        in: query
        required: false
        schema:
          type: string

Here is an example of proxying all requests to https://example.com, where:

  • All headers except Foo-Header and all query parameters except foo_param are provided.
  • The Bar-Header header and the bar_param query parameter are added whose values are an array.
openapi: 3.0.0
info:
  title: Sample API
  version: 1.0.0
paths:
  /{path+}:
    x-yc-apigateway-any-method:
      x-yc-apigateway-integration:
        type: http
        url: https://example.com/{path}
        query:
          '*': '*'
          foo_param: ""
          bar_param: [ "one", "two" ]
          single_param: three
        headers:
          Host: example.com
          '*': '*'
          Foo-Header: ""
          Bar-Header: [ "one", "two" ]
          Single-header: three
        omitEmptyHeaders: true
        omitEmptyQueryParameters: true
      parameters:
      - name: path
        in: path
        required: false
        schema:
          type: string

Use cases

Previous
Static response
Next
Cloud Functions