API REST Кращі практики: аргументи в рядку запиту проти в запиті

126

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

В тілі запиту - У складі тіла json або іншого типу MIME
У рядку запиту - напр/api/resource?p1=v1&p2=v2
Як частина URL-шляху - наприклад/api/resource/v1/v2

Які найкращі практики та міркування щодо вибору між 1 і 2 вище?
Тут висвітлено 2 проти 3 .

— Джонатан
джерело

Чи відповідає це на ваше запитання? Найкращі практики REST API: Де розмістити параметри?

— Стів Чемберс

На додаток до сказаного, як щодо використання заголовка?

— змінна

Відповіді:

Які найкращі практики та міркування щодо вибору між 1 і 2 вище?

Зазвичай тіло вмісту використовується для даних, що підлягають завантаженню / завантаженню на / з сервера, а параметри запиту використовуються для визначення точних запитуваних даних. Наприклад, коли ви завантажуєте файл, ви вказуєте ім'я, тип mime тощо у тілі, але коли ви отримуєте список файлів, ви можете використовувати параметри запиту для фільтрації списку за деякими властивостями файлів. Загалом, параметри запиту є властивістю запиту, а не даними.

Звичайно, це не суворе правило - ви можете його застосовувати будь-яким способом, який вважаєте, що підходить вам / працює.

Ви також можете перевірити статтю wikipedia про рядок запиту , особливо перші два абзаци.

— stan0
джерело

Розумним заходом до вашого вищезгаданого аналізу є те, що ідентичні операції найкраще зберігатись у рядках запиту URL-адреси, а CRUD найкраще зберігати в строго набраних органах відповідей, що, по суті, використовує перевагу SOP і запобігає дуже основні форми соціальних інженерій / фішинг-атак

— Rice

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

Рядок запиту, як частина URL-адреси (URI), він там визначає, який ресурс ви розміщуєте чи виправляєте.

Ви попросили кращих практик, оскільки семантика моя. Звичайно, використання ваших правил великого керування повинно працювати, особливо якщо веб-фреймворк ви використовуєте абстрактно це в параметри .

Ви найбільше знаєте:

Деякі веб-сервери мають обмеження по довжині URI.
Ви можете надіслати параметри всередині тіла запиту за допомогою CURL.
Куди ви надсилаєте дані, це не повинно впливати на налагодження.

— Леонел Галан
джерело

Нижче наведені мої правила ...

Коли користуватися тілом:

Коли аргументи не мають плоского ключа: структура значення
Якщо значення не читаються людиною, наприклад, серіалізовані двійкові дані
Коли у вас дуже велика кількість аргументів

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

Коли аргументи такі, що ви хочете бачити їх під час налагодження
Коли ви хочете мати можливість викликати їх вручну під час розробки коду, наприклад, з curl
Коли аргументи поширені для багатьох веб-служб
Коли ви вже надсилаєте інший тип вмісту, такий як application/octet-stream

Зауважте, що ви можете змішувати та співставляти - помістіть загальні, ті, які слід відладкувати у рядку запиту, а все інше киньте у json.

— Джонатан
джерело

Вибір способу структурування свого API на основі зручності розробки не є хорошою практикою.

— Ерік Штейн

Як сказав @EricStein, ви отримали це назад.

— DanMan

Хлопці, чому я поставив запитання, щоб отримати правильну відповідь. Вперед, напишіть відповідь, і я усуну свою несправедливу. @EricStein

— Джонатан

@Jonathan apis, який легко споживати людськими руками, майже завжди є хорошим апісом. Кудо за точний виклик KISS

— Кріс Марісіч

@AkshayHiremath Він має на увазі той факт, що ви можете надсилати щось інше в тілі, наприклад, якщо ви надіслали заголовок ContentType на зразок "image / jpeg", вам потрібно, щоб тіло повідомлення містило дані jpeg і не могло включати нічого іншого в це

— Шаяан