Рекомендации по REST API: аргументы в строке запроса и в теле запроса

REST API может иметь аргументы в нескольких местах:

1. В теле запроса - как часть тела json или другого типа MIME.
2. В строке запроса - например,/api/resource?p1=v1&p2=v2
3. Как часть URL-пути - например,/api/resource/v1/v2

Каковы лучшие практики и рекомендации по выбору между 1 и 2 выше?
2 против 3 рассматривается здесь .

Каковы лучшие практики и рекомендации по выбору между 1 и 2 выше?

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

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

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

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

Строка запроса, как часть URL-адреса (URI), указывает, какой ресурс вы публикуете или исправляете.

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

Вы знаете больше всего:

• Некоторые веб-серверы имеют ограничения на длину URI.
• Вы можете отправлять параметры внутри тела запроса с помощью CURL.
• То, куда вы отправляете данные, не должно влиять на отладку.

Вот мои практические правила ...

Когда использовать тело:

• Когда аргументы не имеют плоской структуры ключ: значение
• Если значения не читаются человеком, например сериализованные двоичные данные
• Когда у вас очень много аргументов

Когда использовать строку запроса:

• Когда аргументы таковы, что вы хотите видеть их во время отладки
• Если вы хотите иметь возможность вызывать их вручную при разработке кода, например, с помощью curl
• Когда аргументы являются общими для многих веб-сервисов
• Когда вы уже отправляете контент другого типа, например application/octet-stream

Обратите внимание, что вы можете смешивать и сопоставлять - поместите общие, те, которые должны быть отлажены, в строку запроса, а все остальное бросьте в json.