Что такое «ручка» (endpoint) в API: объясняем простыми словами

«Ручка», «эндпоинт», «API-точка входа», «URL-метод-ресурс» — джентльмены, выбирайте оружие. Когда в команде говорят «добавь ещё одну ручку», новичок хмурится и гуглит, а старожил уже пишет POST /api/v1/orders. Но если вас попросили объяснить, что такое ручка в API, а не просто показать пальцем в код, — тут начинается самое интересное. Давайте разберёмся без воды.

Откуда вообще взялось слово «ручка»

В русскоязычной IT-среде endpoint называют ручкой уже лет десять. Это калька с английского слова handle — «рукоятка», «ручка двери». И логика тут простая: вы дёргаете за ручку — и что-то происходит. GET /users — дёрнул, получил список пользователей. POST /users — дёрнул, создал нового. Ручка двери, ручка API — аналогия прижилась, потому что интуитивно понятна.

В английской среде термин endpoint используется чаще, и он ближе к значению «конечная точка». Маршрут построен, сигнал пришёл — вот точка назначения.

Официально, без метафор:

Endpoint (ручка, эндпоинт) — это конкретный URL API-сервера, по которому клиент отправляет HTTP-запрос. Комбинация пути (/users) и HTTP-метода (GET, POST, PUT, DELETE) идентифицирует одно действие: получить, создать, обновить, удалить ресурс.

Ручка — это не HTTP-метод

Самая частая путаница: «GET — это ручка?» Нет. Ручка — это адрес плюс глагол. Тот же путь /users/42 с разными методами — это три разные ручки:

Аналогия: входная дверь в квартиру. Адрес (путь) — «Москва, улица Пушкина, дом 5, квартира 42». А действие — это то, что вы с этой дверью делаете: открываете ключом и заходите (GET), вносите диван (POST), запираете на все замки и уходите (DELETE). Одна и та же дверь, но три разных сценария. Ручка — это сценарий, а не дверь сама по себе.

Если вы хотите разобраться в основных принципах REST API — там разложено, почему метод и URL живут только в связке.

Как endpoint работает: от клика до ответа

Когда вы тыкаете «Обновить профиль» в приложении, под капотом происходит целый маршрут. Вот его схема:

graph LR
  A["Пользователь<br/>браузер / приложение"]
  B["HTTP-запрос<br/>GET /api/v1/users/42"]
  C["API-сервер<br/>маршрутизатор запросов"]
  D["Ручка / endpoint<br/>GET /api/v1/users/:id"]
  E["Обработчик<br/>бизнес-логика"]
  F["База данных<br/>пользователи"]
  G["HTTP-ответ<br/>200 OK + JSON"]
  
  A -->|"1. Клиент отправляет запрос"| B
  B -->|"2. Приходит на"| C
  C -->|"3. Сопоставляет URL с"| D
  D -->|"4. Передаёт обработчику"| E
  E -->|"5. Читает / изменяет"| F
  F -->|"6. Возвращает результат"| E
  E -->|"7. Формирует ответ"| G
  G -->|"8. Ответ уходит клиенту"| A

  style A fill:#7b68ee,stroke:#5a4db2,color:#fff
  style B fill:#f0a500,stroke:#c88400,color:#333
  style C fill:#4a90d9,stroke:#2c5f8a,color:#fff
  style D fill:#50c878,stroke:#3a9a5c,color:#fff
  style E fill:#4a90d9,stroke:#2c5f8a,color:#fff
  style F fill:#7b68ee,stroke:#5a4db2,color:#fff
  style G fill:#50c878,stroke:#3a9a5c,color:#fff

На схеме видно полный цикл: пользователь (фиолетовый) инициирует запрос, он уходит в виде HTTP-сообщения (жёлтый) на сервер. Маршрутизатор (синий) смотрит на URL и HTTP-метод и находит совпадение с зарегистрированным эндпоинтом (зелёный) — ручкой. Та передаёт управление обработчику (синий), он лезет в базу (фиолетовый) и возвращает результат обратно цепочкой — в виде JSON-ответа (зелёный, внизу). Восемь шагов, которые для пользователя выглядят как «нажал — получил».

Примеры эндпоинтов: правильные и не очень

Ручку можно назвать как угодно — сервер не обидится. Но есть конвенции, которые экономят нервы всей команде. Вот живой пример интернет-магазина:

Хорошо:

Плохо (так делают, когда торопятся, а потом страдают):

Чем аккуратнее названы ручки, тем меньше совещаний вида «а что этот эндпоинт вообще делает?». Подробный разбор правил нейминга собрал в посте про правила названий ручек (endpoint) — там со ссылками на RFC и примерами «как надо / как не надо».

Ручки с параметрами: когда одного пути мало

Часто нужно не просто «получить список товаров», а «получить товары со скидкой, отсортированные по цене, для мобильного приложения». Для этого к URL добавляются query-параметры:

1
GET /api/v1/products?category=books&sort=price&limit=20

Это всё та же ручка GET /api/v1/products. Query-параметры не создают новый эндпоинт — они уточняют поведение существующего. Сервер получает запрос, видит ?category=books&sort=price&limit=20 и понимает: «покажи 20 книг, самые дешёвые сверху».

Иная ситуация с path-параметрами вроде {id} — тут GET /api/v1/products/42 и GET /api/v1/products/99 это одна и та же ручка с переменной частью пути. 42 и 99 — просто значения параметра, а не два отдельных эндпоинта (иначе интернет-магазин с миллионом товаров имел бы миллион ручек — представьте swagger на такое).

Как endpoint живёт в спецификации API

В OpenAPI/Swagger-спецификации ручка описывается комбинацией пути и метода. Вот минимальный пример:

1
paths:
2
  /api/v1/products/{productId}:
3
    get:
4
      summary: Получить товар по ID
5
      parameters:
6
        - name: productId
7
          in: path
8
          required: true
9
          schema:
10
            type: integer
11
      responses:
12
        '200':
13
          description: Товар найден

GET + /api/v1/products/{productId} — это одна ручка. Если добавить put и delete в том же блоке paths, появятся ещё две. В YAML это выглядит как вложенные секции, но для API-сервера это три независимых обработчика с разной логикой.

Ручка — это контракт

И вот к чему я веду. Когда вы определяете эндпоинт, вы заключаете контракт с клиентом: «я буду ждать запросы по этому адресу, с такими параметрами, и отвечать такими данными». Клиент (браузер, мобильное приложение, другой сервис) полагается на этот контракт. Если вы завтра переименуете ручку или измените формат ответа, клиент сломается. Это не серебряная пуля, но соблюдение контракта — половина стабильности API.

Собственно, поэтому хороший нейминг эндпоинтов и соблюдение REST-принципов — это не эстетика. Это страховка от звонков в три часа ночи. «У нас продакшен упал, потому что кто-то переименовал /getUser в /fetchUser» — звучит как анекдот, но поверьте, такое происходит регулярно.

Подводя итог: ручка — это пара «HTTP-метод + URL», которая обещает клиенту конкретное действие. Дёрнул GET /users — получил список. Дёрнул DELETE /users/42 — попрощался с пользователем (надеюсь, на тестовом стенде). Всё остальное — договорённости команды о том, как эти ручки называть и что в них передавать.