Rivalry2

HTML Diff

0 added 0 removed

Original 2026-01-01

Modified 2026-02-21

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

2 Содержание

3 <ul><li><a>Что такое API и как он работает</a></li>

4 <li><a>Лучшие практики проектирования API</a></li>

5 <li><a>Как нельзя проектировать API</a></li>

6 </ul>ЭКСПЕРТ

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

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

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

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

11 <ul><li>Снижение затрат.Компания может интегрировать со своим продуктом уже готовые сервисы и не инвестировать в разработку собственного решения. Например, API позволяет подключить к сайту магазина "Яндекс Карты", чтобы показать точное расположение пунктов выдачи товара. Создание собственного картографического сервиса обошлось бы намного дороже.</li>

12 <li>Подробная аналитика.API собирает данные о потребностях и интересах клиентов для оценки их поведения. Например, CPaaS-платформа "<a>МТС Exolve</a>" выводит статистику звонков, заявок и сделок в режиме реального времени, помогая адаптировать маркетинговую кампанию к интересам потребителей.</li>

13 <li>Автоматизация процессов.API может выполнять большую часть бизнес-операций, что существенно снижает нагрузку на менеджеров и освобождает время для более важных дел.</li>

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

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

16 Например:

17 <ul><li>Для добавления нового ролика - POST /videos.</li>

18 <li>Для полной или частичной модификации видео - PUT /videos/:id или PATCH /videos/:id соответственно.</li>

19 <li>Для удаления ролика - DELETE /videos/:id.</li>

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

21 <ul><li>GET - получение данных.</li>

22 <li>POST - отправка информации на сервер.</li>

23 <li>PUT, PATCH - корректировка имеющейся информации.</li>

24 <li>DELETE - очистка данных.</li>

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

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

27 <ul><li>200 OK - запрос выполнен;</li>

28 <li>204 No Content - контент отсутствует;</li>

29 <li>304 Not Modified - нет модификаций;</li>

30 <li><a>400 Bad Request</a> - ошибочный запрос;</li>

31 <li>401 Unauthorized - отказано в доступе;</li>

32 <li><a>403 Forbidden</a> - отказано в авторизации пользователя;</li>

33 <li><a>404 Not Found</a> - запрашиваемый ресурс не получилось найти;</li>

34 <li>409 Conflict - конфликт запроса с текущим состоянием сервера;</li>

35 <li>502 Bad Gateway - целевой сервер не получил данные от шлюза.</li>

36 </ul>Самые частые коды состояния HTTPИнфографика:<a>Richa Sharma</a>/<a>Devstrinx</a>Это далеко не все коды состояния HTTP. Полный список можно посмотреть в документации<a>Mozilla Developer Network</a>. Лучше не перегружать API и использовать только самые популярные коды - так серверу будет проще работать с интерфейсом.

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

38 Сравнение JSON (слева) и XML (справа)Изображение: Skillbox MediaHTTP-методы PUT и PATCH позволяют модифицировать записи на сервере, но делают это по-разному:

39 <ul><li>PUT - обновляет объект полностью, а если в запросе появляются новые поля, то он их создаёт и на сервере;</li>

40 <li>PATCH - обновляет только указанные поля объекта.</li>

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

42 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-запросе передаётся только поле, которое надо изменить:

43 PATCH /goods/1 HTTP/1.1 { "os": { "version": "4.2.2" }, }Тут всё просто: надо соблюдать иерархию и вкладывать объекты в объекты, от которых они зависят. Например, если карточка товара содержит комментарии покупателей, то объект комментария должен входить в URI товара:

44 GET /goods/1/comments HTTP/1.1Это позволяет поддерживать порядок в API и соблюдать логическую связь объектов между собой.

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

46 <ul><li>данные могут попасть в лог и "утечь";</li>

47 <li>чувствительная информация может сохраниться в истории браузера;</li>

48 <li>пользователь может переслать URI.</li>

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

50 PATCH /goods/1?user=managerAB&apikey=0102030405060708 HTTP/1.1 { "os": { "version": "4.2.2" }, }Хорошей практикой будет скрыть его и передать отдельно:

51 PATCH /goods/1 HTTP/1.1 Host: api.example.com user: managerAB apikey: 0102030405060708 { "os": { "version": "4.2.2" }, }Конечная точка API - URL-адрес, с помощью которого можно обратиться к серверу для выполнения операции с помощью программного интерфейса. Допустим, у нас есть API социальной сети и мы хотим получить данные пользователя с идентификационным номером 654122. Тогда надо будет обратиться к следующей конечной точке:

52 https://api.example.com/users/654122Конечные точки бывают публичными и приватными. К первым доступ может получить любой пользователь, а для работы со вторыми надо авторизоваться в системе. Это делается для защиты приватной информации.

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

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

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

56 GET /health HTTP/1.1Если сервер находится онлайн, то он пришлёт такой ответ:

57 HTTP/1.1 200 OKВ ином случае - сообщит о проблеме:

58 HTTP/1.1 502 BAD GATEWAYДаже при соблюдении основных правил построения API разработчики могут допустить неочевидные, но крайне неприятные ошибки. Мы в команде "<a>МТС Exolve</a>" стараемся избегать их. Вот несколько примеров того, что делать не стоит.

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

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

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

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

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

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

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

66 <ul><li>на размере и опыте аудитории;</li>

67 <li>доступных ресурсах и мощности серверов;</li>

68 <li>актуальности текущего интерфейса.</li>

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