Как разработать идеальный Web API: советы и ошибки на этом пути
2026-02-21 17:56 Diff
https://skillbox.ru/media/code/kak-razrabotat-idealnyy-web-api-sovety-i-oshibki-na-etom-puti/

Популярность API растёт из года в год, и всё больше компаний задумывается о разработке быстрых и безопасных интерфейсов. В этой статье вместе с руководителем направления контента сервиса «МТС Exolve» Станиславом Романовым рассказываем о лучших практиках создания API и разбираем типичные ошибки новичков.

Содержание

ЭКСПЕРТ

Руководитель направления контента в «МТС Exolve».

API (англ. application programming interface) — технология обмена данными между двумя приложениями — клиентским и серверным. Взаимодействие между приложениями осуществляется с помощью запросов, которые клиент отправляет серверу.

Допустим, вы оформляете заказ в интернет-магазине. В этот момент сайт магазина отправит запрос к API транспортной компании, чтобы рассчитать стоимость доставки, а во время оплаты — к API платёжного сервиса.

Бизнесу удобно и выгодно использовать API по следующим причинам:

  • Снижение затрат. Компания может интегрировать со своим продуктом уже готовые сервисы и не инвестировать в разработку собственного решения. Например, API позволяет подключить к сайту магазина «Яндекс Карты», чтобы показать точное расположение пунктов выдачи товара. Создание собственного картографического сервиса обошлось бы намного дороже.
  • Подробная аналитика. API собирает данные о потребностях и интересах клиентов для оценки их поведения. Например, CPaaS-платформа «МТС Exolve» выводит статистику звонков, заявок и сделок в режиме реального времени, помогая адаптировать маркетинговую кампанию к интересам потребителей.
  • Автоматизация процессов. API может выполнять большую часть бизнес-операций, что существенно снижает нагрузку на менеджеров и освобождает время для более важных дел.

При всех своих плюсах неудачно спроектированный API может создать много проблем. Например, в работе сторонних приложений могут возникать ошибки, а нарушения обмена данными способны замедлить процессы во всей компании. Чтобы избежать этого, придерживайтесь лучших практик. Разберём их по порядку.

Для обозначения объектов в запросах используйте существительные, а если объект входит в путь запроса, то лучше, чтобы существительные были во множественном числе. Этого требуют стандарты REST API, принятые в сообществе разработчиков. Никто не мешает сделать всё по-своему, но тогда другим программистам будет сложнее работать с вашим интерфейсом.

Например:

  • Для добавления нового ролика — POST /videos.
  • Для полной или частичной модификации видео — PUT /videos/:id или PATCH /videos/:id соответственно.
  • Для удаления ролика — DELETE /videos/:id.

Все действия с данными в Web API производятся с помощью HTTP-методов:

  • GET — получение данных.
  • POST — отправка информации на сервер.
  • PUT, PATCH — корректировка имеющейся информации.
  • DELETE — очистка данных.

Не стоит использовать глаголы в названиях объектов для обозначения действий с данными. Для этого в HTTP есть стандартные методы, которые и так входят в запрос. Например, для получения изображения лучше использовать запрос GET /pictures, а не GET /get-pictures.

С помощью кодов состояния HTTP можно понять, был ли успешно выполнен запрос. Если произошла ошибка, то состояние ответа расскажет, что именно мешает получить данные. Вот самые распространённые HTTP-коды:

  • 200 OK — запрос выполнен;
  • 204 No Content — контент отсутствует;
  • 304 Not Modified — нет модификаций;
  • 400 Bad Request — ошибочный запрос;
  • 401 Unauthorized — отказано в доступе;
  • 403 Forbidden — отказано в авторизации пользователя;
  • 404 Not Found — запрашиваемый ресурс не получилось найти;
  • 409 Conflict — конфликт запроса с текущим состоянием сервера;
  • 502 Bad Gateway — целевой сервер не получил данные от шлюза.
Самые частые коды состояния HTTP
Инфографика: Richa Sharma / Devstrinx

Это далеко не все коды состояния HTTP. Полный список можно посмотреть в документации Mozilla Developer Network. Лучше не перегружать API и использовать только самые популярные коды — так серверу будет проще работать с интерфейсом.

Раньше операции API чаще проводились с помощью XML — расширенного языка разметки. Сегодня главным форматом для взаимодействия с данными стал формат JSON. Для него надо меньше кода, а значит, информация будет передаваться быстрее. Если есть возможность использовать JSON, то лучше выбирать именно этот формат. В свою очередь, XML более функциональный, но работать с ним будет сложнее.

Сравнение JSON (слева) и XML (справа)
Изображение: Skillbox Media

HTTP-методы PUT и PATCH позволяют модифицировать записи на сервере, но делают это по-разному:

  • PUT — обновляет объект полностью, а если в запросе появляются новые поля, то он их создаёт и на сервере;
  • PATCH — обновляет только указанные поля объекта.

Чтобы наглядно увидеть разницу между двумя методами, разберём пример. Допустим, мы хотим отредактировать поле версии операционной системы. Если использовать для этого метод PUT, в запрос придётся передать весь объект:

PUT /goods/1 HTTP/1.1 { "product": "smartphone", "model": "P780", "os":｛ "name": "Android", "version": "4.2.2" }, "prodactionFrom": 2013, "screen": { "resolution": { "width": 720, "height": 1280 }, "diagonal": 5 }, "ram": 1, "drive": 4, "measurements": { "length": 143, "width": 73, "thickness": 9.95 } }

В PATCH-запросе передаётся только поле, которое надо изменить:

PATCH /goods/1 HTTP/1.1 { "os": { "version": "4.2.2" }, }

Тут всё просто: надо соблюдать иерархию и вкладывать объекты в объекты, от которых они зависят. Например, если карточка товара содержит комментарии покупателей, то объект комментария должен входить в URI товара:

GET /goods/1/comments HTTP/1.1

Это позволяет поддерживать порядок в API и соблюдать логическую связь объектов между собой.

В URI нельзя помещать конфиденциальную информацию по следующим причинам:

  • данные могут попасть в лог и «утечь»;
  • чувствительная информация может сохраниться в истории браузера;
  • пользователь может переслать URI.

Например, не стоит помещать API-ключ в URI:

PATCH /goods/1?user=managerAB&apikey=0102030405060708 HTTP/1.1 { "os": { "version": "4.2.2" }, }

Хорошей практикой будет скрыть его и передать отдельно:

PATCH /goods/1 HTTP/1.1 Host: api.example.com user: managerAB apikey: 0102030405060708 { "os": { "version": "4.2.2" }, }

Конечная точка API — URL-адрес, с помощью которого можно обратиться к серверу для выполнения операции с помощью программного интерфейса. Допустим, у нас есть API социальной сети и мы хотим получить данные пользователя с идентификационным номером 654122. Тогда надо будет обратиться к следующей конечной точке:

https://api.example.com/users/654122

Конечные точки бывают публичными и приватными. К первым доступ может получить любой пользователь, а для работы со вторыми надо авторизоваться в системе. Это делается для защиты приватной информации.

Хорошей практикой считается все конечные точки делать с доступом только после аутентификации пользователя. Публичным надо просто разрешить обрабатывать неавторизованные запросы.

Сделайте конечную точку, с помощью которой можно оценить работоспособность службы (например, GET /health). Это позволит другим сервисам проводить нагрузочное тестирование точки и оперативно выявлять возникающие ошибки.

Запрос для проверки доступности сервера может выглядеть так:

GET /health HTTP/1.1

Если сервер находится онлайн, то он пришлёт такой ответ:

HTTP/1.1 200 OK

В ином случае — сообщит о проблеме:

HTTP/1.1 502 BAD GATEWAY

Даже при соблюдении основных правил построения API разработчики могут допустить неочевидные, но крайне неприятные ошибки. Мы в команде «МТС Exolve» стараемся избегать их. Вот несколько примеров того, что делать не стоит.

Оптимизируя API, многие разработчики забывают, что часть имеющихся интеграций тесно связана с прежней версией интерфейса. Вот почему изменение или удаление используемых клиентами ресурсов и шаблонов может критически повлиять на производительность некоторых интеграций. Риск особенно высок при исправлении устаревшего API.

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

Конечная точка — это место, откуда API получает доступ к ресурсам, необходимым для выполнения запроса. Её можно использовать как путь к запрашиваемым данным. Однако перенасыщенность конечных точек для разных методов API может сбить пользователя с толку.

Решение: создавайте только точки, которые по-настоящему нужны. Это поможет повысить производительность API за счёт снижения числа запросов.

Предоставление пользователям доступа ко всем данным и ресурсам API может повысить время обработки и создать лишнюю нагрузку внутренних серверов. В итоге это негативно скажется на продуктивности всей системы.

Решение: если API использует несколько клиентов, лучше всего назначить каждому из них уникальный набор разрешений. Так, доступ к общедоступной информации предоставляется всем без авторизации, а закрытые данные — только аутентифицированным клиентам.

Разработка эффективного API — это трудоёмкий процесс, требующий гибкости и дальновидности. При создании API компаниям следует сосредоточиться не только на стандартах технической части интерфейса, но и на особенностях своего бизнеса, например:

  • на размере и опыте аудитории;
  • доступных ресурсах и мощности серверов;
  • актуальности текущего интерфейса.

Только в этом случае API займёт достойное место среди ваших маркетинговых инструментов и принесёт бизнесу дополнительных покупателей и доход.