Насколько должны быть упрощены возвратные данные API по сравнению с моделью данных? - PullRequest
Новая
       14

Насколько должны быть упрощены возвратные данные API по сравнению с моделью данных?

1 голос
/ 09 февраля 2012

Я разрабатываю несколько RESTful API, и модель данных является относительно сложной и нормализованной.Насколько простым должны быть возвращаемые данные API?

Лучше практиковать замену внешних ключей или идентификаторов фактическими данными из связанной таблицы или лучше возвращать то, что находится в базе данных, и предоставлять методы API для преобразованияэти идентификаторы в полезный контент?Или ... лучше использовать идентификаторы в дополнение к используемым данным?

Вот пример необработанных данных из базы данных в возвращаемых данных: 

<books>
  <book-id>935</book-id>
  <book-author-id>64</book-author-id>
  <book-genre-id>5</book-genre-id>
</books>

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

<books>
  <book-name>Steve Jobs</book-name>
  <author-name>Walter Isaacson</author-name>
  <book-genre-name>biography</book-genre-name>
</books>

Ответы [ 2 ]

3 голосов
/ 11 февраля 2012

Это действительно будет зависеть от того, как будут использоваться ваши данные. Как правило, в любое время, когда вам необходимо углубиться в детали, вы можете указать URL-адрес или идентификатор, который можно использовать.

Для вашего примера, Title - это не то, что вам, вероятно, понадобится, чтобы когда-либо предоставлять более подробную информацию, поэтому вы, вероятно, в безопасности, просто включив его напрямую. Жанр также не нуждается в дополнительных деталях, но люди могут захотеть получить все другие книги этого жанра.

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

Автором должен быть сам ресурс. Так должен жанр. Оба со ссылками на них.

Для разработки реального API-интерфейса вам нужно немного денормализовать свои ресурсы. Объединения ад по http. Предполагая, что почти всем, кто выбирает книгу, также понадобится имя автора, вы должны включить его в ресурс книг. Им также может понадобиться другая информация об авторе, например, его фотография.

Итак, для вашего примера API мы получили что-то вроде этого ... 

<books>
  <title>Steve Jobs</book-name>
  <author href="http://example.com/author/64">
        <name>Walter Isaacson</name>
        <photo>http://images.example.com/author/64/photo</photo>
    </author>
  <genre href="http://example.com/genre/5">biography</genre>
</books>

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

0 голосов
/ 11 февраля 2012

В целом, я бы сказал, что ваш API должен соответствовать требованиям пользователей API. В частности, «разоблачить модель данных» не является хорошей целью. На самом деле вы можете представить некоторые части модели данных, возможно, упрощенные, чтобы соответствовать требованиям. Но общий ответ «делай или не раскрывай внешние ключи», и это будет полностью зависеть от требований.

...