Как разработать идеальный Web API: советы и ошибки на этом пути

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

Содержание

• Что такое API и как он работает
• Лучшие практики проектирования API
• Как нельзя проектировать API

ЭКСПЕРТ

Станислав Романов

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

Что такое API и как он работает

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

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

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

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

Читайте также:

Что такое API и как он работает

Лучшие практики проектирования API

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

Используйте существительные для обозначения объектов

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

Например:

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

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

Читайте также:

Методы GET и POST в HTTP

Используйте коды состояния HTTP

С помощью кодов состояния 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. Полный список можно посмотреть в документации Mozilla Developer Network. Лучше не перегружать API и использовать только самые популярные коды — так серверу будет проще работать с интерфейсом.

Читайте также:

Тест: что вы знаете про статусные коды HTTP?

Отдавайте предпочтение JSON

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

Заменяйте PUT на PATCH

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 нельзя помещать конфиденциальную информацию по следующим причинам:

• данные могут попасть в лог и «утечь»;
• чувствительная информация может сохраниться в истории браузера;
• пользователь может переслать 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

Читайте также:

REST API: что это такое и как работает

Как нельзя проектировать API

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

Ошибка 1

Неуместная модификация действующей API

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

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

Ошибка 2

Перегруз конечными точками

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

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

Ошибка 3

Открытый доступ к API

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

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

Заключение

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

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

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