Каковы наилучшие методы добавления метаданных в ответ RESTful JSON?

Ответ 1

У вас есть несколько способов передать метаданные в RESTful API:

• Код состояния Http
• Заголовки
• Тело ответа

Для metadata.status используйте код состояния Http, для чего! Если метаданные относятся ко всему ответу, вы можете добавить его как поля заголовка. Если метаданные относятся только к части ответа, вам нужно будет внедрить метаданные как часть объекта. НЕ НЕ обернуть весь ответ в искусственном конверте и разделить обертку на данные и метаданные.

И, наконец, будет согласован в вашем API с вашими вариантами.

Хорошим примером является GET для целой коллекции с разбиением на страницы. GET/items Вы можете вернуть размер коллекции и текущую страницу в пользовательские заголовки. И ссылки на страницы в стандартном заголовке заголовка:

Link: <https://api.mydomain.com/v1/items?limit=25&offset=25>; rel=next

Проблема с этим подходом заключается в том, когда вам нужно добавить метаданные, ссылающиеся на определенные элементы в ответе. В этом случае просто вставьте его в сам объект. И иметь последовательный подход... добавлять всегда все метаданные к ответу. Поэтому, возвращаясь к GET/items, представьте, что каждый элемент создал и обновил метаданные:

{
  items:[
    {
      "id":"w67e87898dnkwu4752igd",
      "message" : "some content",
      "_created": "2014-02-14T10:07:39.574Z",
      "_updated": "2014-02-14T10:07:39.574Z"
    },
    ......
    {
      "id":"asjdfiu3748hiuqdh",
      "message" : "some other content",
      "_created": "2014-02-14T10:07:39.574Z",
      "_updated": "2014-02-14T10:07:39.574Z"
    }
  ],
  "_total" :133,
  "_links" :[
     {
        "next" :{
           href : "https://api.mydomain.com/v1/items?limit=25&offset=25"
         } 
   ]
}

Обратите внимание, что ответ коллекции является частным случаем. Если вы добавляете метаданные в коллекцию, сбор больше не может быть возвращен как массив, это должен быть объект с массивом в нем. Почему объект? потому что вы хотите добавить некоторые атрибуты метаданных.

Сравните с метаданными в отдельных элементах. Ничто не близко к обертыванию объекта. Вы просто добавляете некоторые атрибуты в ресурс.

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

Ответ 2

Вдоль строк комментария @Charlie: для фрагментации вашего вопроса вам все равно нужно выпекать метаданные в ответ так или иначе, но атрибуты status и message здесь несколько избыточны, так как они уже покрыты по самому протоколу HTTP (статус 200 - найденная модель, 404 - модель не найдена, 403 - недостаточно привилегий, вы получаете эту идею) (см. spec). Даже если ваш сервер возвращает условие ошибки, вы все равно можете отправить часть message в качестве тела ответа. Эти два поля будут покрывать большую часть ваших потребностей в метаданных.

Лично я склонялся к (ab) с помощью пользовательских заголовков HTTP для небольших фрагментов метаданных (с префиксом X-), но я предполагаю, что предел, где это становится непрактичным, довольно низок.

несколько расширился в вопросе с меньшим объемом, но я думаю, что пункты по-прежнему актуальны для этого вопроса.

Ответ 3

У нас был тот же вариант использования, в котором нам нужно было добавить метаданные разбиения на страницы на ответ JSON. Мы закончили создание типа коллекции в Backbone, который мог бы обрабатывать эти данные, и легкую обертку на стороне Rails. Этот пример просто добавляет метаданные в объект коллекции для ссылки в представлении.

Итак, мы создали класс Backbone Collection что-то вроде этого

// Example response:
// { num_pages: 4, limit_value: 25, current_page: 1, total_count: 97
//   records: [{...}, {...}] }

PageableCollection = Backbone.Collection.extend({
  parse: function(resp, xhr)  {
    this.numPages = resp.num_pages;
    this.limitValue = resp.limit_value;
    this.currentPage = resp.current_page;
    this.totalCount = resp.total_count;
    return resp.records;
  }  
});

И затем мы создали этот простой класс на стороне Rails, чтобы генерировать метаданные при разбиении на страницы с Kaminari

class PageableCollection
  def initialize (collection)
    @collection = collection
  end
  def as_json(opts = {})
    {
      :num_pages => @collection.num_pages 
      :limit_value => @collection.limit_value 
      :current_page => @collection.current_page,
      :total_count => @collection.total_count
      :records => @collection.to_a.as_json(opts)
    }
  end
end

Вы используете его в таком контроллере

class ThingsController < ApplicationController
  def index 
    @things = Thing.all.page params[:page]
    render :json => PageableCollection.new(@things)
  end
end

Enjoy. Надеюсь, вы сочтете это полезным.