Contact UsGet started

Resource relationships in API Gateway

Written by
Improved by
Updated at April 18, 2025

An API gateway is an interface for working with services in Yandex Cloud or on the internet.

API gateways are set in a declarative way using specifications. A specification is a JSON or YAML file with an API gateway description based on the OpenAPI 3.0 standard. In API Gateway, the specification includes extensions for integration with other cloud platforms.

Available extensions:

Algorithm for a handler search in the OpenAPI specification

When searching for a handler, API Gateway does the following:

  1. Selects routes in the OpenAPI specification matching the request being processed.

  2. Sorts the selected routes by priority:

    • The highest priority is given to fixed routes, which do not contain path parameters and greedy parameters, e.g., /simple/path.
    • Routes that contain path parameters but do not have any greedy parameters get the medium priority, e.g., /{param}/path.
    • The lowest priority is given to routes with greedy parameters, e.g., /{greedy_param+}.

    If two routes have the same priority:

    • Two routes with medium priority are consistently compared across URL segments. There are two types of segments: fixed (e.g., simple) and parameterized (e.g., {param}). A fixed segment has a higher priority than a parameterized one. If all route segments have the same priority, the longer route is selected.
    • If two routes have the lowest priority, the longer one is selected.

Examples of route comparison

/a/{param1}/b and /a/{param2}/{param3}

Both routes have medium priority because they contain path parameters, but do not contain greedy parameters, so they are consistently compared across URL segments.

  1. The a and a segments are both fixed and have the same priority.
  2. The {param1} and {param2} segments are both parameterized and have the same priority.
  3. The b segment is fixed and the {param3} segment is parameterized, so the b segment is selected.

Thus, /a/{param1}/b is selected as a handler.

/a/b/{param1} and /a/{param2}/d

Both routes contain path parameters but do not contain greedy parameters, so they have medium priority and are consistently compared across URL segments.

  1. The a and a segments are both fixed and have the same priority.
  2. The b segment is fixed and the {param2} segment is parameterized, so the b segment is selected.

Thus, /a/b/{param1} is selected as a handler.

/a/b/{param+} and /a/{param2}/d

The /a/b/{param+} route contains a greedy parameter, which means it has the lowest priority. The /a/{param2}/d route contains a path parameter, but does not contain a greedy parameter, so it has medium priority. Out of the medium and lowest-priority routes, the route with the medium priority is selected.

Thus, /a/{param2}/d is selected as a handler.

/a/{param} and /a/{prm}

Both routes contain path parameters but do not contain greedy parameters, so they have medium priority and are consistently compared across URL segments.

  1. The a and a segments are both fixed and have the same priority.
  2. The {param} and {prm} segments are both parameterized and have the same priority.

Since it is not possible to select a route based on segments, the route lengths are compared. The /a/{param} route is longer than the /a/{prm} route.

Thus, /a/{param} is selected as a handler.

/a/{param1}/{param+} and /a/{param2}/{prm+}

Both routes contain greedy parameters, so they have the lowest priority and their lengths are compared. The /a/{param1}/{param+} route is longer than the /a/{param2}/{prm+} route.

Thus, /a/{param1}/{param+} is selected as a handler.

Using domains

API Gateway allows you to add your own domain to access the API gateway. To establish a TLS connection, you can use certificates added in Certificate Manager.

For more information on connecting your own domain to the API gateway, see Connecting a domain.

For more information on adding certificates, see Adding a Let's Encrypt® certificate.

Authorization

API Gateway enables you to implement common authentication and authorization algorithms as described in the OpenAPI 3.0 specification. Currently, you can use authorization using a function and using JWT.

WebSocket

Note

This feature is in the Preview stage.

For two-way asynchronous communication between clients and an API gateway, API Gateway supports the WebSocket protocol. Clients can send messages to an API gateway, which in turn can independently send messages to client applications. This means clients can receive data without having to make an HTTP request. Web sockets are often used in apps that require real-time data updates, such as messengers and online chats, multiplayer games, collaboration tools, trading apps, and sports betting services.

To connect to an API gateway using WebSocket, you can use a service domain allocated when creating the API gateway or any other domain added to the API gateway.

Integrations are supported for the following events:

  • Opening a connection.
  • Sending messages via a web socket.
  • Closing a connection.

To set up integrations, you can use special extensions in the OpenAPI specification.

You can manage web sockets using the API that receives information about a connection, sends data to the client side, and closes the connection.

For limits related to WebSocket support, see Quotas and limits.

To view an example of a serverless WebSocket app, click here.

See also

Previous
API Gateway protection with Smart Web Security
Next
Networking