Три фишки хорошего API

Сегодня программные интерфейсы приложений (API) находятся в самом центре современной архитектуры ПО.

API – это как пользовательские интерфейсы, только пользователями здесь выступают программы.

Признак успешного API – когда получаешь совсем не то, что планировалось, и люди в итоге создают такие вещи, которые вообще не ожидаешь.

На конференции Apidays один из докладчиков дал дельные советы о том, как избежать наиболее распространенных ошибок на этапе проектирования API.

FinBase.com.ua предлагает отдельно рассмотреть каждый из них.

#1: Используйте HTTP POST вместо GET

Вообще использование HTTP POST встречается достаточно редко, поскольку GET – гораздо более популярный метод получения данных, чем POST. Так сложилось исторически. При этом GET обычно приводит к появлению длинных URL, в которых бывает сложно разобраться. Впрочем, такими является большинство запросов, поэтому GET де-факто стал главным методом построения фильтрованных запросов с помощью HTTP. Также стоит заметить, что длинные URL любит Google, так что они хороши для поисковой оптимизации.

Однако приложения для веба, работающие через браузер, используя GET могут столкнуться с проблемой. Из-за того, что некоторые браузеры (а особенно Chrome) хороши в кешировании, если браузер видит постоянно повторяющийся GET – например, нажатие кнопки назад – в итоге у вас могут возникнуть две посадочные страницы для одной формы.

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

Чтобы решить эту проблему, лучше пользоваться POST, а не GET, поскольку согласно спецификации HTTP метод POST не кешируется.

Если вы все-таки получаете кешированные API-запросы и сложно понять почему, тогда стоит посмотреть на следующие моменты:

• Добавьте POST там где это возможно (держите в уме тот факт, что смена GET на POST на изменение взаимодействия с API, а это повлияет на внешние приложения).
• Добавьте ?cache_buster=[random] к любому GET (это один из способов поддержки статуса-кво, если смена GET на POST может сильно отобразиться на других девелоперских проектах).

#2: Используйте сжатие часто используемых API

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

Чтобы идентифицировать проблему, стоит спросить себя:

• У вас есть большие дата-сеты?
• Эти запросы вам дорого обходятся?
• Ваши данные меняются достаточно часто?
• У вас большое количество клиентов?

Если на все вопросы вы получаете утвердительный ответ, то в качестве быстрого решения можно использовать вебхуки (webhooks), которые по сути являются обратным API. Вместо того, чтобы спрашивать, мы отправляем им POST когда есть что-то новое. И разница в трафике впечатляет, поскольку вебхуки снижают количество запросов.

Вебхук – это уведомление, которое отправляется в сеть автоматически при возникновении определенного события. Уведомления отправляются через HTTP POST, а тело запроса – в формате JSON.

Кроме этого, можно попробовать и другие способы:

• кеширование (хотя это скользкий момент)
• копия базы данных (только для чтения)

#3: Формируйте группы запросов

Что делать, если для обновления всей информации в веб-приложении требуется сделать 10-20 отдельных запросов к API? Обычно такая ситуация приводит к эффекту пробки и существенному замедлению работы приложения. В качестве одного из решений может сброс REST по методу GraphQL.

Суть состоит в том, чтобы подумать как клиент собирается слать запросы и как будет использоваться ваш инструментарий. Это что-то типа N+1 запросов, когда вызов идет на главный элемент, который потом сбрасывается на подчиненные ему элементы. Если найти похожие паттерны в запросах ваших пользователей, то можно снизить количество обращений к API c помощью построения специфического слоя (так называемый бэкэнд для фронтэнда).

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