REST API - согласованность формата JSON

Question

Я искал в Интернете это и не нашел ответа на довольно простой вопрос: должны ли форматы JSON быть одинаковыми для всех HTTP-глаголов для определенного ресурса?

Например:

GET http://example.com/api/articles возвращает

[
  {
    id: 1,
    ref: "21313-453542"
  },
  {
    id: 2,
    ref: "23424-234243"
  }, ...
]

GET http://example.com/api/articles/2 возвращает

{
  id: 2,
  ref: "23424-234243",
  name: "Cofee",
  price: 23,
  provider: "112-411",
}

Это хорошая практика, или объекты JSON должны всегда иметь согласованный формат? Чтобы было ясно, если форматы должны быть согласованы, первый запрос должен возвращать что-то вроде этого:

[
  {
    id: 1,
    ref: "21313-453542",
    name: "Oranges",
    price: 34,
    provider: "2424-12",
  }
  {
    id: 2,
    ref: "23424-234243",
    name: "Cofee",
    price: 23,
    provider: "112-411",
  }
]

Answer 1

Определите шаблон объекта (обычно карту) для каждого типа ресурса, который у вас есть.

/ api / resources (GET) - должен перечислить все ресурсы

/ api / resources / $ resource_id (GET) - должен возвращать определенный ресурс

/ api / resources (POST) - должен создать и вернуть вновь созданный ресурс

/ api / resources / $ resource_id (PUT) - должен возвращать определенный отредактированный ресурс

/ api / resources / $ resource_id (DELETE) - установить код ответа HTTP 204 (без содержимого)

Только список ресурсов api должен давать список объектов. Все остальные типы API могут возвращать только карту объектов.

Оптимизация ширины полосы: Если вы хотите ограничить данные, отправляемые клиенту, вы можете поддержать параметр запроса fields . Если это поле не задано, вы можете вернуть все объектное представление вашего ресурса. / API / ресурсы? = Поля ID, исх

Answer 2

По моему мнению, вы должны использовать ту же "схему" для данных JSON, возвращаемых с конечных точек, которые вы даете в качестве примера, поскольку я ожидаю, что вызов API http://example.com/api/articles/2 можно использовать для получения одной статьи , тогда как http://example.com/api/articles можно использовать для получения всех доступных статей , но представление данных article такое же.

Если вы хотите предоставить «компактное» представление сущностей статьи, например, используя только атрибуты id и ref, как в вашем первом представлении JSON, вы должны предоставить другую конечную точку API, например:

http://example.com/api/articles-refs или http://example.com/api/articles/refs

Вы должны принять эту стратегию представления для любого подходящего глагола HTTP (например, GET, POST, PUT), в то время как глаголы, такие как DELETE, обычно требуют только id объекта для удаления, так как дополнительный объект атрибуты бесполезны для конкретной операции API.

Это приводит к последовательному и простому в использовании API, ИМХО.

В любом случае, вы всегда должны документировать свой API, чтобы предоставлять потребителям API информацию о доступных операциях, их семантике и JSON-схеме ввода / вывода данных.

Вы можете использовать Swagger / OpenAPI для документации API. Если вы используете Java для реализации своего API, я опубликовал статью об этом на DZone .

Answer 3

Мои рекомендации:

1. Форматы должны быть согласованными. Это делает документацию намного проще.
2. Заменить везде id поле на uri поле. Лучше, если клиент всегда видит URI вместо идентификаторов.

Например:

{
  uri: "http://example.com/api/articles/2",
  ref: "23424-234243",
  name: "Cofee",
  price: 23,
  provider: "112-411",
}

Answer 4

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

Так что хорошей идеей будет разделить ваши взгляды таким образом.