[Документация Yandex Cloud](../../index.md) > [Yandex API Gateway](../index.md) > Концепции > Взаимосвязь ресурсов сервиса

# Взаимосвязь ресурсов в API Gateway

_API-шлюз_ — это интерфейс взаимодействия с сервисами внутри Yandex Cloud или в интернете.

API-шлюз задается декларативно при помощи спецификации. Спецификация — это файл в формате JSON или YAML с описанием API-шлюза по стандарту [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification). В сервисе API Gateway спецификация дополнена расширениями, которые вы можете использовать для интеграции с другими облачными платформами.

Доступные расширения:
* [Статический ответ](extensions/dummy.md)
* [Обращение по HTTP](extensions/http.md)
* [Интеграция с Cloud Functions](extensions/cloud-functions.md)
* [Интеграция с Serverless Containers](extensions/containers.md)
* [Интеграция с Smart Web Security](extensions/sws.md)
* [Интеграция с Object Storage](extensions/object-storage.md)
* [Интеграция с DataSphere](extensions/datasphere.md)
* [Интеграция с Data Streams](extensions/datastreams.md)
* [Интеграция с Message Queue](extensions/ymq.md)
* [Интеграция с YDB](extensions/ydb.md)
* [Интеграция с Swagger UI](extensions/swagger.md)
* [Жадные параметры](extensions/greedy-parameters.md)
* [Обобщенный HTTP-метод](extensions/any-method.md)
* [Авторизация с помощью функции Cloud Functions](extensions/function-authorizer.md)
* [Авторизация с помощью JWT](extensions/jwt-authorizer.md)
* [Поддержка протокола WebSocket](extensions/websocket.md)
* [Валидация данных](extensions/validator.md)
* [Поддержка CORS](extensions/cors.md)
* [Параметризация спецификации](extensions/parametrization.md)
* [Канареечный релиз](extensions/canary.md)
* [Ограничение скорости обработки запросов](extensions/rate-limit.md)
* [Замена кода ответа](extensions/status-mapping.md)
* [Преобразование тела ответа и запроса](extensions/schema-mapping.md)

## Алгоритм поиска обработчика в OpenAPI-спецификации {#algorithm}

При поиске обработчика API Gateway:
1. Выбирает в [OpenAPI-спецификации](../../glossary/openapi.md) маршруты, которые соответствуют обрабатываемому запросу.
1. Сортирует выбранные маршруты по приоритетам:
    * Наивысший приоритет имеют фиксированные маршруты — маршруты, которые не содержат параметры пути и [жадные параметры](extensions/greedy-parameters.md). Например: `/simple/path`.
    * Средний приоритет имеют маршруты, которые содержат параметры пути, но не содержат жадные параметры. Например: `/{param}/path`.
    * Наименьший приоритет имеют маршруты с жадными параметрами. Например: `/{greedy_param+}`.

    Если у двух маршрутов одинаковый приоритет:
    * Два маршрута со средним приоритетом последовательно сравниваются по сегментам URL. Сегменты бывают двух видов — фиксированные (например, `simple`) и параметризованные (например, `{param}`). Фиксированный сегмент является более приоритетным, чем параметризованный. Если у всех сегментов маршрутов одинаковый приоритет, выбирается тот маршрут, длина которого больше.
    * Между двумя маршрутами с наименьшим приоритетом выбирается тот, длина которого больше.

### Примеры сравнения маршрутов

{% cut "`/a/{param1}/b` и `/a/{param2}/{param3}`" %}

Оба маршрута имеют средний приоритет, потому что содержат параметры пути, но не содержат жадные параметры, поэтому последовательно сравниваются по сегментам URL.

1. Сегменты `a` и `a` — оба фиксированные и имеют одинаковый приоритет.
1. Сегменты `{param1}` и `{param2}` — оба параметризованные и имеют одинаковый приоритет.
1. Сегмент `b` — фиксированный, а `{param3}` — параметризованный, поэтому выбирается сегмент `b`.

Выбранный обработчик — `/a/{param1}/b`.

{% endcut %}

{% cut "`/a/b/{param1}` и `/a/{param2}/d`" %}

Оба маршрута содержат параметры пути, но не содержат жадные параметры, поэтому имеют средний приоритет и последовательно сравниваются по сегментам URL.

1. Сегменты `a` и `a` — оба фиксированные и имеют одинаковый приоритет.
1. Сегмент `b` — фиксированный, а `{param2}` — параметризованный, поэтому выбирается сегмент `b`.

Выбранный обработчик — `/a/b/{param1}`.

{% endcut %}

{% cut "`/a/b/{param+}` и `/a/{param2}/d`" %}

Маршрут `/a/b/{param+}` содержит жадный параметр, поэтому имеет наименьший приоритет. Маршрут `/a/{param2}/d` содержит параметр пути, но не жадный параметр, поэтому имеет средний приоритет. Между маршрутом со средним и наименьшим приоритетом выбирается маршрут со средним приоритетом.

Выбранный обработчик — `/a/{param2}/d`.

{% endcut %}

{% cut "`/a/{param}` и `/a/{prm}`" %}

Оба маршрута содержат параметры пути, но не содержат жадные параметры, поэтому имеют средний приоритет и последовательно сравниваются по сегментам URL.

1. Сегменты `a` и `a` — оба фиксированные и имеют одинаковый приоритет.
1. Сегменты `{param}` и `{prm}` — оба параметризованные и имеют одинаковый приоритет.

Так как нельзя выбрать между всеми сегментами, сравниваются длины маршрутов. Маршрут `/a/{param}` длиннее маршрута `/a/{prm}`.

Выбранный обработчик — `/a/{param}`.

{% endcut %}

{% cut "`/a/{param1}/{param+}` и `/a/{param2}/{prm+}`" %}

Оба маршрута содержат жадные параметры, поэтому имеют наименьший приоритет и сравниваются по длине. Маршрут `/a/{param1}/{param+}` длиннее маршрута `/a/{param2}/{prm+}`.

Выбранный обработчик — `/a/{param1}/{param+}`.

{% endcut %}

## Использование доменов {#domains}

Сервис API Gateway позволяет подключить собственный домен для обращения к API-шлюзу. Для организации TLS-соединения можно использовать сертификаты, добавленные в сервисе Certificate Manager.

Подробнее о подключении собственного домена к API-шлюзу в разделе [Подключить домен](../operations/api-gw-domains.md).

Подробнее о добавлении сертификатов в разделе [Добавить сертификат от Let's Encrypt®](../../certificate-manager/operations/managed/cert-create.md).

## Авторизация {#authorization}

API Gateway позволяет реализовать стандартные [механизмы аутентификации и авторизации](https://swagger.io/docs/specification/authentication/), которые предусмотрены спецификацией [OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification). На данный момент доступна [авторизация с помощью функции](extensions/function-authorizer.md) и [авторизация с помощью JWT](extensions/jwt-authorizer.md).

## WebSocket {#websocket}

{% note info %}

Эта функциональность находится на стадии [Preview](../../overview/concepts/launch-stages.md).

{% endnote %}

Для организации асинхронного двунаправленного взаимодействия между клиентами и API-шлюзом сервис API Gateway поддерживает протокол [WebSocket](https://yandex.cloud/ru/blog/posts/2023/04/yandex-api-gateway-and-websocket#podderzhka-protokola-websocket-v-api-gateway). Клиенты могут отправлять сообщения в API-шлюз, который в свою очередь может независимо отправлять сообщения клиентским приложениям. Такая возможность позволяет клиентам получать данные без необходимости делать HTTP-запрос. Веб-сокеты часто используются в приложениях, требующих обновления данных в режиме реального времени, таких как мессенджеры и онлайн-чаты, многопользовательские игры, платформы для совместной работы, а также приложения финансового рынка и спортивные онлайн-площадки.

Чтобы подключиться к API-шлюзу по протоколу WebSocket, можно использовать служебный домен, выделяемый при создании API-шлюза, или любой другой, добавленный к API-шлюзу.

Доступны интеграции на следующие события:
* открытие соединения;
* отправка сообщений через веб-сокет;
* закрытие соединения.

Для настройки интеграций предусмотрены [специальные расширения](extensions/websocket.md) OpenAPI-спецификации.

Управлять веб-сокетами можно с помощью [API](../api-ref/websocket/authentication.md), который позволяет получить информацию о соединении, отправить данные на клиентскую сторону и закрыть соединение.

Ограничения, связанные с поддержкой протокола WebSocket, описаны в разделе [Квоты и лимиты](limits.md).

[Пример serverless-приложения с использованием протокола WebSocket](http://github.com/yandex-cloud-examples/yc-serverless-game).
 
#### Полезные ссылки {#see-also}

* [Обзор доступных расширений](extensions/index.md)