Только POST? Давайте закончим этот абсурдный спор о дизайне API

Недавно мне привлекла внимание дискуссия о том, стоит ли разрабатывать API, используя "только POST". После погружения в этот спор я обнаружил, что не только сам вопрос, о котором спорят люди, бессмыслен, но он также выявляет непонимание многими разработчиками сути дизайна API. Сегодня давайте глубже проникнем в основные идеи дизайна API и посмотрим, почему этот спор не должен был возникнуть с самого начала.

Неправильное представление о "только POST"#

Те разработчики, которые выступают за использование "только POST" для замены спецификаций RESTful API, явно не поняли самого важного момента в дизайне API. Их аргументы обычно включают:

1. Упрощение дизайна: Один метод может справиться со всем
2. Безопасность: Параметры POST не отображаются в URL
3. Гибкость: POST может отправлять любую структуру данных

На первый взгляд, эти аргументы кажутся логичными. Но на самом деле эта точка зрения путает выбор методов HTTP с API стилем дизайна, что является вопросами разных уровней. POST — это всего лишь один метод протокола HTTP, в то время как REST — это стиль дизайна API.

Суть дизайна API#

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

1. Понятным и доступным: Другие разработчики (включая вас в будущем) должны интуитивно понимать назначение каждого эндпоинта
2. Последовательным: Следовать определенным спецификациям для снижения затрат на обучение
3. Расширяемым: Способным легко выполнять контроль версий и расширение функционала
4. Эффективным: Учитывать эффективность с точки зрения производительности и использования ресурсов

RESTful API: Больше чем просто выбор методов HTTP#

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

1. Получить все статьи:

2. Получить конкретную статью:

3. Создать новую статью:

4. Обновить статью:

5. Удалить статью:

В этом примере мы видим:

• API спроектирован вокруг ресурса "article"
• Различные методы HTTP используются для отображения различных операций
• Структура URL четкая, указывая на ресурс, над которым выполняется операция

Этот подход к дизайну делает API более интуитивно понятным и самоочевидным, что облегчает разработчикам понимание функции каждого эндпоинта.

RPC: Понимание стиля API за "только POST"#

Цель дизайна RPC (Remote Procedure Call) API заключается в том, чтобы сделать вызовы удаленных сервисов такими же простыми, как и вызовы локальных функций.

Интересно, что те, кто выступает за "только POST", могут даже не осознавать, что они фактически описывают стиль RPC.

По сравнению с RESTful API, RPC больше фокусируется на самой операции, а не на ресурсе. Именно поэтому API в стиле RPC обычно используют форму "глагол + существительное", например getProduct(productId) или createUser(userData).

Во многих реализациях RPC, все операции обычно отправляются через POST запросы на один и тот же эндпоинт, а специфическая операция и параметры указываются в теле запроса. Вот почему идея "только POST" на самом деле ближе к RPC, чем к REST.

Например, RPC-запрос "получить продукт" на основе HTTP может выглядеть так:

Современные RPC фреймворки, такие как gRPC, предоставляют более мощные и эффективные реализации. Давайте используем это в качестве примера для демонстрации стиля RPC:

Сначала мы определяем сервис и формат сообщений (используя Protocol Buffers):

Затем, использование этого сервиса в клиенте на Node.js так же просто, как вызов локальной функции:

В этом примере стиля RPC мы можем видеть:

1. Определение сервиса четко перечисляет все доступные операции (в этом упрощенном примере GetArticle и CreateArticle).
2. Каждая операция имеет четко определенные типы запросов и ответов.
3. Код клиента выглядит как вызов локальной асинхронной функции, используя await для ожидания результата, что дальше скрывает сложность сетевой коммуникации.
4. Нет необходимости вручную составлять HTTP запросы или разбирать JSON ответы.

Хотя на нижнем уровне все еще может использоваться HTTP/2 как транспортный протокол, фреймворки RPC (такие как gRPC) предоставляют разработчикам уровень абстракции, который делает вызовы удаленных сервисов похожими на вызовы локальных функций.

Таким образом, мы видим, что большинство дебатов о "только POST" и RESTful API должны на самом деле быть обсуждениями этих двух стилей API: REST и RPC. Однако ключевым моментом является осознание того, что оба стиля имеют свои применимые сценарии, и выбор должен основываться на конкретных потребностях проекта, а не на личных предпочтениях.

REST против RPC: Нет абсолютного превосходства#

Теперь, когда мы разобрались в различиях между REST и RPC, давайте рассмотрим их соответствующие применимые сценарии:

1. REST подходит для:
   • Приложений, ориентированных на ресурсы (например, системы управления контентом, блоговые платформы, сайты электронной коммерции)
   • Сценариев, где требуется хорошая поддержка кэша (GET запросы естественно кэшируются)
   • Проектов, которые хотят использовать семантику HTTP (например, использование соответствующих статус-кодов)
   • Публичных API, которые требуют хорошей обнаруживаемости и самоописания
2. RPC подходит для:
   • Приложений, ориентированных на действия (например, сложные операции обработки данных, контроль рабочих процессов)
   • Систем, требующих высокой производительности и низкой задержки (например, системы реального времени)
   • Взаимодействия между внутренними микросервисами (которые могут требовать более гибкой передачи параметров)
   • Когда операции не могут быть просто сопоставлены с CRUD (Create, Read, Update, Delete) операциями

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

Заключение#

1. Суть дизайна API заключается в четкости, последовательности, расширяемости и эффективности, а не в соблюдении определенного метода или стиля.
2. Оба стиля, RESTful и RPC, являются зрелыми парадигмами дизайна API. Выбор между ними должен основываться на требованиях проекта, а не на личных предпочтениях.
3. Если вы решите использовать "только POST", то, пожалуйста, проектируйте ваш API в соответствии со стилем RPC. Как и RESTful, это широко используемая спецификация API в индустрии, но она должна использоваться в подходящих сценариях.
4. Не путайтесь в поверхностных технических деталях. Что действительно важно, так это то, может ли ваш API эффективно обслуживать ваших пользователей и бизнес цели.
5. При разработке API тратьте больше времени на размышления о вашей модели ресурсов, бизнес-логике и потребностях пользователей, а не на том, какой метод HTTP использовать.

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