Ми запускаємо новий API REST, і я хотів би отримати деякі відомості про найкращі практики щодо того, як у нас повинні бути відформатовані вхідні параметри:
Зараз наш API дуже орієнтований на JSON (повертає лише JSON). Дебати про те, чи хочемо ми / мусимо повернути XML - це окрема тема.
Оскільки наш вихід API є орієнтованим на JSON, ми пішли вниз по шляху, де наші входи трохи зосереджені на JSON, і я думав, що може бути зручно для деяких, але загалом дивних.
Наприклад, щоб отримати кілька деталей продукту, де ми можемо витягнути відразу декілька продуктів:
http://our.api.com/Product?id=["101404","7267261"]
Чи варто спростити це як:
http://our.api.com/Product?id=101404,7267261
Або зручне введення JSON? Більше болю?
Ми можемо захотіти прийняти обидва стилі, але чи справді гнучкість викликає більше плутанини та болі в голові (ремонтопридатність, документація тощо)?
Складніший випадок - це коли ми хочемо запропонувати більш складні входи. Наприклад, якщо ми хочемо дозволити кілька фільтрів у пошуку:
http://our.api.com/Search?term=pumas&filters={"productType":["Clothing","Bags"],"color":["Black","Red"]}
Ми не обов'язково хочемо розміщувати типи фільтрів (наприклад, тип товару та колір) як такі назви запитів:
http://our.api.com/Search?term=pumas&productType=["Clothing","Bags"]&color=["Black","Red"]
Тому що ми хотіли згрупувати весь вхід фільтра разом.
Зрештою, це насправді має значення? Можливо, там є стільки утиліт JSON, що тип введення просто не має великого значення.
Я знаю, що наші клієнти JavaScript, які здійснюють дзвінки AJAX до API, можуть оцінити входи JSON, щоб полегшити їхнє життя.
[]
синтаксис не завжди підтримується (і незважаючи на те, що він є загальним, може навіть порушити специфікацію URI). Деякі сервери HTTP та мови програмування віддають перевагу просто повторенню назви (наприкладproductType=value1&productType=value2
).