Использование JSON в качестве формата параметров запроса API (разработка API для моего веб-приложения)

Question

Я разрабатываю API для своего веб-приложения, и наш контент довольно сложный. Например, у вас может быть страница вики с несколькими подобъектами, такими как теги, несколько отдельных областей содержимого и т. Д.

Я не хочу иметь дело со сложным, грязным способом именования параметров, таких как tag_N или tag [].

Мне также пришло в голову, что наши объекты могут быть совершенно выражены как JSON. На самом деле, это наш формат ответа. Если вы делаете GET, вы получаете объект в формате JSON.

Разумно ли требовать, чтобы тело объекта POST и PUT также указывалось в JSON? Например, что-то вроде этого:

{
 'name' : 'My Page',
 'body' : 'Some page body',
 'tags' : ['tag1', 'tag2', 'tag3']
}

в отличие от

name=My%20Page&body=Some%20page%20body&tag[]=tag1&tag[]=tag2&tag[]=tag3

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

Итак, главный вопрос: если мы требуем, чтобы тело POST было строкой JSON, это неразумно? Это слишком далеко от нормы HTTP API? Будете ли вы, как автор потребителя API, откладывать API с таким требованием?

Answer 1

Это не лишено смысла.Здесь вы можете смешивать несколько вещей: (а) формат данных, (б) кодирование и (в) философию дизайна REST.

Как правило, я бы предложил следующее:

• Форматы данных должны быть согласованными (например, JSON как основа для всех методов CRUD для ресурса; было бы неплохо, если бы вы также поддерживали XML из-за его повсеместности - многие фреймворки делают это автоматически для вас)

• Кодировка должна быть отделена от формата передачи данных;например, URL имеют кодировку, которая немного отличается от кодировки тела.Не путайте это с форматом данных.

• Предложите вам смоделировать ресурс настолько полно, насколько это возможно.Используйте POST для создания, GET для чтения, PUT для обновления и DELETE для удаления в большинстве случаев

Answer 2

Это довольно типично для API JAX-RS / REST.