Skip to main content
Version: 1.3.x

OpenAPI Extensions

OpenAPIExtension​

Metadata describing an extension to the OpenAPI spec.

FieldDescriptionValidation Rule

name

string
The name of the OpenAPI extension as it should appear in the OpenAPI document. For example: x-tsb-service

–

appliesTo

List of string
Parts of the OpenAPI spec where this custom extension is allowed. This is a list of names of the OpenAPI elements where the extension is supported. For example: ["info", "path"]

–

required

bool
Flag that configures if the extension is mandatory for the elements where it is supported.

–

OpenAPIExtensions​

Available OpenAPI extensions to configure APi Gateway features in Service Bridge.

FieldDescriptionValidation Rule

x-tsb-service

string
Short name of the service in the TSB service registry where the path is exposed. if the extension is configured in the info section, all paths in the spec will be mapped to this service.

This service name will be used to generate all the routes for traffic coming to the associated paths.

OpenAPI extension name: x-tsb-service
Applies to: info, path
Required: Required unless x-tsb-redirect is defined for the target paths.

Example:

openapi: 3.0.0
info:
  title: Sample API
  version: 0.1.9
  x-tsb-service: productpage.bookinfo
paths:
  /users:
    x-tsb-service: productpage.bookinfo
    get:
      summary: Returns a list of users.

–

x-tsb-redirect

tetrateio.api.tsb.gateway.v2.Redirect
Configures a redirection for the given path. If a redirection is configured for a given path, the x-tsb-service extension can be omitted.

OpenAPI extension name: x-tsb-redirect
Applies to: path
Required: false

Example:

paths:
  /users:
    x-tsb-redirect:
      uri: /v2/users
    get:
      summary: Returns a list of users.

–

x-tsb-tls

tetrateio.api.tsb.gateway.v2.ServerTLSSettings
Configures the TLS settings for a given server. If omitted, the server will be configured to serve plain text connections.

OpenAPI extension name: x-tsb-redirect
Applies to: server
Required: false

Example:

openapi: 3.0.0
servers:
  - url: http://api.example.com/v1
    x-tsb-tls:
      mode: SIMPLE
      secretName: api-certs

–

x-tsb-cors

tetrateio.api.tsb.gateway.v2.CorsPolicy
Configures CORS policy settings for the given server. Note that Service Bridge does not currently support per-path CORS settings, so this applies at a server level.

OpenAPI extension name: x-tsb-cors
Applies to: server
Required: false

Example:

openapi: 3.0.0
servers:
  - url: http://api.example.com/v1
    x-tsb-cors:
      allowOrigin:
        - "*"

–

x-tsb-authentication

tetrateio.api.tsb.gateway.v2.Authentication
Configures Authentication rules for the given server. This extension must be configured if the Authorization is configured with rules based on JWT tokens.

OpenAPI extension name: x-tsb-authentication
Applies to: server
Required: Required if Authorization is based on JWT tokens.

Example:

openapi: 3.0.0
servers:
  - url: http://api.example.com/v1
    x-tsb-authentication:
      jwt:
        issuer: https://www.googleapis.com/oauth2/v1/certs
        audience: bookinfo

–

x-tsb-external-authorization

tetrateio.api.tsb.gateway.v2.Authorization.ExternalAuthzBackend
Configures an external authorization server to handle all authorization requests for the configured server.

OpenAPI extension name: x-tsb-external-authorization
Applies to: server
Required: false

Example:

openapi: 3.0.0
servers:
  - url: http://api.example.com/v1
    x-tsb-external-authorization:
      uri: http://authz-server.example.com
      includeRequestHeaders:
        - Authorization # forwards the header to the authorization service.

–

x-tsb-jwt-authorization

tetrateio.apo.tsb.application.v2.OpenAPIExtensions.JWTAuthz
Configures Authorization based on JWT tokens.

Note that if this is configured, the x-tsb-authentication extension must be configured for the servers so the tokens can be properly validated and trusted before reading their contents to enforce access control rules.

This can be applied at the server or path level. When applied at the server level, the authorization rules will be enforced for all paths in that server.

OpenAPI extension name: x-tsb-jwt-authorization
Applies to: server, path
Required: false

Example:

openapi: 3.0.0
servers:
  - url: http://api.example.com/v1
    x-tsb-authorization:
      claims:
        - iss: https://www.googleapis.com/oauth2/v1/certs
          sub: expected-subject
          other:  # Additional claims to require int he token
            group: engineering
paths:
  /users:
    x-tsb-authorization:  # Override the server settings for the given path
      claims:
        - other:
            group: admin

–

x-tsb-ratelimiting

List of tetrateio.api.tsb.gateway.v2.RateLimitSettings.RateLimitRule
Configures settings for ratelimiting requests

This can be applied at the server and path level. Each ratelimit setting is independant of the other. The dimensions are automically populated based on the path attributes, and users are allowed to append more dimensions as well

OpenAPI extension name: x-tsb-ratelimiting
Applies to: server, path
Required: false

Example:

openapi: 3.0.0
servers:
  - url: http://api.example.com/v1
    # Ratelimit at 10 requests/minute for every HTTP GET request 
    # with a unique value in the x-user-id header
    x-tsb-ratelimiting:
      - dimensions:
          - header:
              name: x-user-id
          - header:
              name: ":method"
              value:
                exact: GET
        limit:
          requestsPerUnit: 10
          unit: MINUTE
paths:
  /users:
    # Ratelimit at 5 requests/second for every HTTP request
    # with a path value of /users
    x-tsb-ratelimiting: 
      - limit:
          requestsPerUnit: 5
          unit: SECOND

–

JWTAuthz​

Configures authorization rules based on the JWT token in an incoming request.

FieldDescriptionValidation Rule

claims

List of tetrateio.api.tsb.gateway.v2.Subject.JWTClaims
List of claims to be required for incoming requests.

–