Skip to main content

Configure OpenAPI Resources

Load document from file​

In this example, Relixy loads the OpenAPI 2.0 document of JSON Placeholder. The ref property accepts a path or an HTTP URL to a YAML or JSON file.

# yaml-language-server: $schema=https://raw.githubusercontent.com/relychan/relixy/refs/heads/main/jsonschema/relixy.schema.json
version: v1
kind: OpenAPI
metadata:
  name: jsonplaceholder
definition:
  ref: https://raw.githubusercontent.com/hasura/ndc-http/main/connector/testdata/jsonplaceholder/swagger.json

Define an inline document​

OpenAPI 3.x only

The inline document supports OpenAPI 3.x only. If your API uses an OpenAPI 2.0 document, save it to a file and load it via ref instead.

warning

ref and spec are mutually exclusive — use one or the other, not both.

You can define the document manually with the spec property.

# yaml-language-server: $schema=https://raw.githubusercontent.com/relychan/relixy/refs/heads/main/jsonschema/relixy.schema.json
version: v1
kind: OpenAPI
metadata:
  name: jsonplaceholder
definition:
  spec:
    servers:
      - url: https://jsonplaceholder.typicode.com
    paths:
      /albums:
        get:
          operationId: getAlbums
          description: "Get albums"
      /posts/{id}:
        get:
          operationId: getPostById
          description: "Get post by ID"

The inline specification is not strict — you don't need to define the full spec. However, Relixy will proxy requests directly without validating the request or response.

Overlay patches​

Use patches to extend an OpenAPI document without modifying the original file. This is useful for customizing third-party API specs. The setting is compatible with Action objects of the Overlay specification.

In this example, the server URL is overridden with an environment variable.

# yaml-language-server: $schema=https://raw.githubusercontent.com/relychan/relixy/refs/heads/main/jsonschema/relixy.schema.json
version: v1
kind: OpenAPI
metadata:
  name: jsonplaceholder
definition:
  ref: https://raw.githubusercontent.com/hasura/ndc-http/main/connector/testdata/jsonplaceholder/swagger.json
  patches:
    - target: $.servers[0].url
      update: "{SERVER_URL}"
note

A patch is skipped if the target's parent object or array does not exist. For example, a patch targeting $.servers[1].url has no effect when the array has only one item.

Base path​

By default, an OpenAPI resource is mounted at the root path. When multiple OpenAPI resources are configured, each must have a unique base path to avoid routing conflicts.

# yaml-language-server: $schema=https://raw.githubusercontent.com/relychan/relixy/refs/heads/main/jsonschema/relixy.schema.json
version: v1
kind: OpenAPI
metadata:
  name: default
definition:
  settings:
    basePath: "/api/v1"
  # ...

In the example above, all endpoints in the resource are prefixed with /api/v1 — for example, /api/v1/albums.

Additional headers​

Add static headers to every upstream request with the headers property. A header value can be a literal string or an environment variable reference.

# yaml-language-server: $schema=https://raw.githubusercontent.com/relychan/relixy/refs/heads/main/jsonschema/relixy.schema.json
version: v1
kind: OpenAPI
metadata:
  name: default
definition:
  settings:
    headers:
      X-Custom-Header:
        value: foo
      X-Api-Key:
        env: SERVER_API_KEY
  # ...

Forwarding headers​

Use forwardHeaders to pass headers between the client and the upstream service:

  • request: Header names forwarded from the client request to the upstream service.
  • response: Header names forwarded from the upstream response back to the client.
# yaml-language-server: $schema=https://raw.githubusercontent.com/relychan/relixy/refs/heads/main/jsonschema/relixy.schema.json
version: v1
kind: OpenAPI
metadata:
  name: default
definition:
  settings:
    forwardHeaders:
      request:
        - Authorization
      response:
        - X-Custom-Header
  # ...

HTTP client​

The http field configures HTTP client behavior, including timeout and retry.

# yaml-language-server: $schema=https://raw.githubusercontent.com/relychan/relixy/refs/heads/main/jsonschema/relixy.schema.json
version: v1
kind: OpenAPI
metadata:
  name: default
definition:
  settings:
    http:
      timeout: 60
      retry:
        maxAttempts: 3
        delay: 1000
        multiplier: 1.5
        maxDelay: 5000
  • timeout: Maximum request timeout in seconds. Set to 0 or omit to disable.
  • retry: Default retry policy using exponential backoff.
    • maxAttempts: Maximum number of retry attempts.
    • delay: Initial wait time in milliseconds before the first retry. Subsequent delays grow according to multiplier and jitter. Defaults to 1000 (1 second).
    • multiplier: Growth factor for the retry interval. Must be >= 1. Use 1 for a constant interval. Defaults to 1.5.
    • maxDelay: Maximum delay in milliseconds. If less than or equal to delay, the interval remains constant. Unlimited by default.

See the full reference for HTTP client settings.

Next steps​