Способ указания списка полей ресурсов в запросе API RESTful

У меня есть RESTful API в веб-сервисе с такими ресурсами, как пользователи, сообщения и т.д. Когда я делаю запрос на список сообщений (GET/posts), я хочу получить массив сообщений только с уменьшенной частью данных для каждого сообщения (т.е. Темы, имени автора). Когда я делаю запрос на конкретный пост (GET/posts/42), я хочу получить полный список полей post object, включая большой почтовый ящик, дополнительную информацию о том, как нравится подсчет, количество комментариев. Я полагаю, существует множество способов решения этой проблемы. На мой взгляд, 3 наиболее очевидны:

  • Явное указание полей по каждому запросу (/posts? fileds = subject, author_name и для /сообщений/42? = поля предмет, тело, createaAt, author_name, comments_count, LIKES_COUNT и т.д...).
  • Явным образом укажите список полей только в том случае, если он отличается от стандартного список полей.
  • Укажите список полей, которые должны быть исключены (или inlcuded) из (до) полей по умолчанию, заданных, если желаемые поля устанавливаются по-разному.

Я создаю ясный и полезный API для своих клиентов. Какой способ выбрать?

Ответы

Ответ 1

Я бы выбрал вариант 2 IMHO.

Итак, если потребитель просто запрашивает url ресурсов (/posts/42), они получают поля по умолчанию.

Затем потребители могут изменить ответ по умолчанию, задав значения в querystring, например:/posts/42/fields? subject, author_name

Это хорошо сработало для меня в прошлом и как работают некоторые другие хорошо известные API. Facebook

Изменить: Оглядываясь назад, я бы изменил запрос:/posts/42? fields = subject, author_name,/post/42 - это поля ресурсов.

Ответ 2

Проводили исследования в этом, а также указали на Facebook GraphQL в качестве альтернативы запросить приятный api с нужными полями. Он все еще находится на ранней стадии, но кажется очень перспективным.

https://facebook.github.io/react/blog/2015/05/01/graphql-introduction.html

EDIT: Воспроизводится по URL-адресу:

Запрос GraphQL - это строка, интерпретируемая сервером, который возвращает данные в указанном формате. Вот пример запроса:

{
  user(id: 3500401) {
    id,
    name,
    isViewerFriend,
    profilePicture(size: 50)  {
      uri,
      width,
      height
    }
  }
}

(Примечание: этот синтаксис несколько отличается от предыдущих примеров GraphQL. Недавно мы улучшили язык.)

И вот ответ на этот запрос.

{
  "user" : {
    "id": 3500401,
    "name": "Jing Chen",
    "isViewerFriend": true,
    "profilePicture": {
      "uri": "http://someurl.cdn/pic.jpg",
      "width": 50,
      "height": 50
    }
  }
}