👉 Можно ли использовать метод POST для получения данных?
Да, можно.

Метод POST изначально предназначен для отправки данных на сервер с целью их обработки и создания новых записей в БД. В то же время его можно использовать для получение данных в следующих случаях:

1️⃣ Запросы на получение данных (списки объектов) с большим количеством фильтров
Когда необходимо реализовать большое количество фильтров для получения списка, то решение отправлять их все в URL запроса как query-параметры не лучшее, т.к. это делает URL очень длинным. Это может вызвать проблемы с ограничениями на длину URL в некоторых веб-серверах или браузерах.

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

Пример:

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

Метод "Получение списка книг с применением фильтров":

GET https://test-system.com/api/books?author=Толстой&genre=роман&year=1877&publisher=Огонек&rating=5&...

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

Вместо этого, можно использовать метод POST для передачи всех этих параметров в теле запроса в формате JSON:

Метод "Создание поискового запроса на получение списка книг с применением фильтров":
POST https://test-system.com/api/books/search

{
"author": "Толстой",
"genre": "роман",
"year": 1877,
"publisher": "Огонек",
"rating": 5,
...
}

Такой подход делает запрос более структурированным и читаемым, избегая проблем с длиной URL. Кроме того, это позволяет легко расширять список фильтров в будущем без страха ограничений.

В двух этих примерах результат будет идентичный: тело ответа со списком книг, отфильтрованных по заданным пользователем параметрам.

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

2️⃣ Асинхронные запросы на получение данных: комбинирование POST и GET
Асинхронные запросы на получение данных реализуются за счет комбинации методов POST и GET.

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

Реализуются асинхронные запросы последовательным использованием методов:

🔹 POST - используется для создания задачи на сервере. При получении такого запроса, сервер помещает задачу в очередь на обработку и возвращает идентификатор задачи.

🔹 GET - с помощью этого метода можно проверить статус выполнения задачи, используя идентификатор, предоставленный на предыдущем шаге. Как только задача завершена, через этот же метод можно получить результаты его выполнения.

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

1. Пользователь отправляет POST-запрос для формирования отчета по продажам. При этом в теле запроса передаются параметры, необходимые для формирования отчета, такие как диапазон дат, тип отчета или другие фильтры.

Метод размещения запроса на формирование отчета:

POST /api/reports/sales

{
"startDate": "2023-01-01",
"endDate": "2023-12-31"
}

После обработки этого запроса сервер создает задачу на формирование отчета и помещает ее в очередь.

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

{
"taskId": "12345"
}

2. Через некоторое время пользователь может отправить GET-запрос, чтобы проверить, готов ли отчет или получить его, если он готов.

Метод получения информации по статусу формирования отчета или готового отчета:

GET /api/reports/sales/status/{taskId}
Если отчет еще формируется:

{
"status": "progress"
}

Если отчет уже готов, пользователь может скачать его, используя предоставленный URL в ответе или получить его структуру. Зависит от выбранного способа реализации.

Пример, если в ответ на отчет готова ссылка на его загрузку:

{
"status": "completed",
"reportUrl": "/api/reports/sales/download/12345"
}

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

Представим, что вы создаете API для системы бронирования авиабилетов. Пользователь хочет найти билеты на определенную дату.

1. Пользователь отправляет POST-запрос с деталями поиска (дата, пункт назначения и т.д.).

Метод размещения запроса на поиск авиабилетов:

POST /api/tickets/search

{
"departure": "2023-10-30",
"destination": "Rome",
...
}

Сервер возвращает идентификатор задачи - идентификатор созданного запроса на поиск.

{
"searchId": "Уникальный идентификатор задачи"
}

2. Через некоторое время пользователь делает GET-запрос с этим идентификатором, чтобы узнать статус поиска.

Метод получения статуса или информации по результатам поиска, если он завершен:

GET /api/tickets/search/{searchId}
или
GET /api/tickets/search/status/{searchId}

Ответ (если поиск еще не завершен):

{
"status": "progress"
}

Как только поиск завершен, пользователь получает список доступных рейсов в ответ на GET-запрос.

✅ Этот подход обеспечивает эффективное использование ресурсов сервера и хороший UX для пользователя, который не вынужден ждать завершения длительных операций, а может поставить задачу на получение данных в фон, или получать результаты поиска быстро и порциями, по мере сбора данных из разных систем (помните, когда во время поиска авиабилетов у вас постоянно добавляются новые и новые записи?).

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

👉 Можно ли в GET передавать тело запроса?
Не стоит, оно будет проигнорировано или обрезано.

HTTP-спецификация не запрещает передачу тела запроса в методе GET, но этот подход считается нестандартным и может вызвать определенные проблемы и вопросы при разработке и использовании API.

Почему передача тела запроса в GET может показаться привлекательной? В некоторых сценариях может возникнуть потребность в передаче сложных данных для фильтрации или поиска, которые сложно или невозможно передать через URL в виде query-параметров.

Главная проблема такого подхода: не все клиенты и серверы поддерживают передачу тела запроса в методе GET. Некоторые из них могут игнорировать тело запроса или возвращать ошибку. Проще говоря, тело запроса будет проигнорировано или "обрезано".

👉 Как правильно именовать эндпоинты - ед. число или мн. число (/user или /users)?
Можно и так, и так. Но нужно ориентироваться на то, как названы остальные эндпоинты в проекте. В новом API предложили бы делать в ед. числе, т.к. было больше опыта в этом.

В именовании ресурсов в REST API есть разные подходы, и, честно говоря, нет строгого стандарта.

Однако на практике чаще всего предпочитают использовать единственное число для ресурсов. Но и множественное число также активно используется!

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

Примеры:

Единственное число:
GET /task/123 - получить информацию о задаче с ID 123.
POST /task - создать новую задачу.

Множественное число:
GET /tasks - получить список всех задач
GET /tasks/123 - получить информацию о задаче с ID 123.
POST /tasks - создать новую задачу.

✅ Множественное число представляет собой коллекцию элементов, что соответствует идеологии REST для метода добавления нового элемента в коллекцию и чтения списка - /tasks читается легче, где у вас есть коллекция ресурсов и конкретные ресурсы внутри этой коллекции.

Рекомендации по множественному числу есть в гайдлайнах:

1) Microsoft API Guidelines: 7.4.1. POST ---> POST http://api.contoso.com/account1/servers

2) Google Cloud API Design Guide: Resource names ---> Example 1: A storage service has a collection of buckets, where each bucket has a collection of objects

При этом, если мы взглянем на Яндекс:

Пример с ед. числом:
https://yandex.ru/dev/rasp/doc/ru/reference/nearest-settlement

Пример с мн. числом:
https://yandex.ru/dev/market/partner-api/doc/ru/overview/express

📌 Наглядный пример как в рамках одной огромной компании работали разные команды.

От чего зависит выбор? От опыта команды, и как комфортнее воспринимать методы при чтении.

Помимо этих источников, хорошей практикой также является изучение и анализ популярных публичных API, чтобы увидеть общепринятые стандарты в сообществе. А лучшая практика - посмотрите как у вас уже реализован API в компании!

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

Хотя я предпочитаю единственное число, для меня важнее договоренность с командой и поддержка единого подхода на протяжении всего проекта.

🗓💥 [30.10 в 19:00 Мск] Postman, Insomnia и AI для REST API — на практике 💥🗓

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


👉 Приглашаем вас на бесплатный онлайн-практикум, чтобы разобраться с темой и освоить три инструмента, которые реально ускоряют работу аналитика и дают лучшее понимание REST API:

💥 Postman, Insomnia и AI — на практике:
проверим чужие API и спроектируем свои REST API-методы с нуля

🗓 30 октября (чт), в 19:00 МСК
🟢 Онлайн

🔗 Зарегистрироваться

План:
1. Теория по REST API - только то, что пригодится в практике.
2. Postman & Insomnia: создаём коллекции и проверяем внешние API.
3. Настройка AI-ассистента для работы с проектированием REST API.
4. Проектирование и документация собственного REST API-метода в Insomnia + AI.


Это полноценное обучение, которое даст вам реальный опыт работы с REST API и тремя самыми актуальными инструментами 🚀

--------
Занятие проводится в качестве вводного урока к практической программе Дизайн REST API.
--------

Регистрируйтесь и подключайтесь онлайн в следующий четверг! 😉