# API

Настройка API предоставляет API-интерфейсы на основе [gRPC](https://grpc.io/) для удаленного вызова.

Интерфейсы можно включить с помощью модуля конфигурации api.  Когда API включен, Xray создает исходящее подключение с тем же тегом, что и тег API.  
Необходимо вручную направить все входящие API-подключения на это исходящее подключение с помощью [правил маршрутизации](./routing.md).  
См. раздел [Связанные настройки](#связанные-настройки) в этом документе.

Начиная с версии [v1.8.12](https://github.com/XTLS/Xray-core/releases/tag/v1.8.12) поддерживается упрощенный режим настройки, в котором достаточно указать только ApiObject, без необходимости настройки inbounds и routing.  
Однако при использовании упрощенной настройки статистика трафика не учитывает трафик входящих API-подключений.

::: warning
Большинству пользователей не нужен этот API, новички могут просто пропустить этот раздел.
:::

## ApiObject

`ApiObject` соответствует полю `api` в конфигурационном файле.

```json
{
  "api": {
    "tag": "api",
    "listen": "127.0.0.1:8080",
    "services": ["HandlerService", "LoggerService", "StatsService", "RoutingService"]
  }
}
```

> `tag`: string

Тег исходящего подключения.

> `listen`: string

IP-адрес и порт, на котором прослушивает API-сервер.  Это необязательный параметр.

Если этот параметр опущен, необходимо добавить настройки inbounds и routing, как показано в примере в разделе [Связанные настройки](#связанные-настройки).

> `services`: \[string\]

Список включенных API.  
Доступные значения см. в разделе [Список API](#список-поддерживаемых-api).

## Связанные настройки

Можно добавить входящее подключение api в раздел inbounds:

```json
"inbounds": [
  {
    "listen": "127.0.0.1",
    "port": 10085,
    "protocol": "dokodemo-door",
    "settings": {
      "address": "127.0.0.1"
    },
    "tag": "api"
  }
]
```

Добавить правило маршрутизации для входящего подключения api в раздел routing:

```json
"routing": {
  "rules": [
    {
      "inboundTag": [
        "api"
      ],
      "outboundTag": "api",
      "type": "field"
    }
  ]
}
```

Добавить api в основные настройки:

```json
"api": {
  "tag": "api",
  "services": [
    "StatsService"
  ]
}
```

## Список поддерживаемых API

### HandlerService

API для изменения входящих и исходящих подключений.  
Доступны следующие функции:

- Добавление нового входящего подключения;
- Добавление нового исходящего подключения;
- Удаление существующего входящего подключения;
- Удаление существующего исходящего подключения;
- Добавление пользователя к входящему подключению (поддерживается только для VMess, VLESS, Trojan, Shadowsocks (v1.3.0+));
- Удаление пользователя из входящего подключения (поддерживается только для VMess, VLESS, Trojan, Shadowsocks (v1.3.0+));

### RoutingService

API для добавления, удаления, замены правил маршрутизации и запроса статистики балансировщика.  
Доступны следующие функции:

- adrules - добавление или замена правил маршрутизации;
- rmrules - удаление правил маршрутизации;
- sib - разрыв соединений с указанного IP-адреса;
- bi - запрос статистики балансировщика;
- bo - принудительное переключение балансировщика на указанный outboundTag.

Конкретное использование можно узнать с помощью команды `./xray help api bi`.

### LoggerService

Поддержка перезапуска встроенного логгера.  
Можно использовать совместно с logrotate для управления файлами журналов.

### StatsService

Встроенная служба статистики данных.  
См. [Статистика](./stats.md).

### ReflectionService

Позволяет gRPC-клиентам получать список API сервера.

```bash
$ grpcurl -plaintext localhost:10085 list
grpc.reflection.v1alpha.ServerReflection
v2ray.core.app.proxyman.command.HandlerService
v2ray.core.app.stats.command.StatsService
xray.app.proxyman.command.HandlerService
xray.app.stats.command.StatsService
```

## Примеры вызова API

[Xray-API-documents](https://github.com/XTLS/Xray-API-documents) @crossfw