Skip to main content
logoTetrate Service BridgeVersion: 1.4.x

OpenAPI Extensions

OpenAPI Extensions available to configure APIs.

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.auth.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.auth.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.api.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

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

This can be applied at the server, path and operation level. Each rate limit setting is independent of the other. Top level fields such as failClosed and timeout can be only be specified at the server level. The dimensions are automatically 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, operation
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:
      failClosed: false
      timeout: 0.03s
      rules: 
      - 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:
      rules:
      - limit:
          requestsPerUnit: 5
          unit: SECOND
    post:
      # Ratelimit at 10 requests/second for every HTTP request
      # with a values /users for path and POST for method
      x-tsb-ratelimiting:
        rules:
        - limit:
            requestsPerUnit: 10
            unit: SECOND

–

x-tsb-external-ratelimiting

tetrateio.api.tsb.gateway.v2.ExternalRateLimitServiceSettings
Configures settings for ratelimiting requests using an external ratelimit server This can be applied at the server, path and operation level. Each setting is independent of the other. Top level fields such as domain and rateLimitServerUri must only be specified at the server level. The 'headersfield within theheaderValueMatch dimension field is automatically populated when this annotation is used at the path and operation level and theheaders` field is unset. Users are allowed to append more values as well.

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

Example:

openapi: 3.0.0
servers:
  - url: http://api.example.com/v1
    # This configuration will emit a list of descriptors - 
    # ("remote_address", "<trusted address from x-forwarded-for>"),
    # ("header_match", "desc-value-1") only for GET requests,
    # ("desc-key-1", "<header_value_queried_from_header>") only when
    # the request contains the header x-user-id
    # These descriptors are sent as a request to grpc://ratelimiter.bar.com
    # with the domain field set to "my-api-domain"
    # The response from the server decides whether this request will be
    # ratelimited or not.
    x-tsb-external-ratelimiting:
      domain: "my-api-domain"
      rateLimitServerUri: "grpc://ratelimiter.bar.com"
      rules:
      - dimensions:
          - requestHeaders:
              headerName: "x-user-id"
              descriptorKey: "desc-key-1"    
          - headerValueMatch:
              descriptorValue: "desc-value-1"
              headers: 
                ":method":
                exact: "GET"
          - remoteAddress: {} 
paths:
  /users:
    # This configuration will emit the descriptor 
    # ("header_match", "desc-value-2") when the :path header is set to /users.
    # This descriptor is sent as part of the request to grpc://ratelimiter.bar.com
    # with the domain field set to "my-api-domain".
    # The response from the server decides whether this request will be
    # ratelimited or not.
    x-tsb-external-ratelimiting:
      rules:
      - dimensions:
          - headerValueMatch:
              descriptorValue: "desc-value-2"
    post:
      # This configuration will emit the descriptor 
      # ("header_match", "desc-value-3") when the :path header is set to /users
      # and the :method header is set to GET.
      # This descriptor is sent as part of the request to grpc://ratelimiter.bar.com
      # with the domain field set to "my-api-domain"
      # The response from the server decides whether this request will be
      # ratelimited or not.
      x-tsb-external-ratelimiting:
        rules:
        - dimensions:
            - headerValueMatch:
                descriptorValue: "desc-value-3"

–

JWTAuthz​

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

FieldDescriptionValidation Rule

claims

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

–