Как представить (перечислить) типы в публичном API

32

Я работаю над простым API-интерфейсом, который хочу использовать для собственного клиента и который будет открыт для публики в будущем. У меня есть объекты «Предмет», которые могут иметь разные «типы». Тип является C "typedef enum", на данный момент у меня есть:

typedef enum {
    ItemTypeBool,
    ItemTypeNumber,
    ItemTypeDate,
} ItemType;

(Я могу добавить некоторые в будущем)

Мне интересно, лучше ли мне передавать его как целые числа или как определенные «строки». JSON будет:

Для целых чисел:

{
  "name": "The name",
  "type": 0,
   ...
}

Для строк:

{
  "name": "The name"
  "type": "boolean"
   ...
}

Мне интересно, есть ли лучшая практика для этого. Сохранение целого числа немного упростит код и уменьшит пропускную способность, но разработчикам будет легче запомнить строки. Я помню, что работал над проектом, и я должен был помнить 1 = изображение, 2 = аудио, 3 = HTML, ... что не имеет никакого реального смысла.

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

api patterns-and-practices enum Julien
источник
Ожидаете ли вы, что ваши пользователи будут часто редактировать JSON вручную?
Джеймс

Ответы:

39

Предоставьте строки. Числа не имеют смысла. Вы не используете их в своем собственном коде, верно (вы оборачиваете перечисляемые значения, которые в основном являются строками) - зачем наказывать пользователя необходимостью использовать эти числа?

Единственный профессионал, если вы выставляете цифры - вам легче их разобрать. Но эй, кто заботится о тебе. Позаботьтесь о клиентах API.

Если вы предоставите строки - проще для клиентов; никогда не придется говорить такие вещи, как «4 устарели в пользу 17»; немного сложнее разбирать от вашего имени, но это нормально.

Не предоставляйте и то и другое: как пользователь, мне остается задуматься

  • какой я использую? И то и другое? [на чтение документов]
  • почему есть два способа сказать то же самое? они немного отличаются? [на чтение документов]
  • что если я укажу оба, и будет несоответствие? это будет жаловаться? один будет иметь приоритет? который из? [на чтение документов]

Как вы видите, вы заставляете меня читать много документов без причины.

Iluxa
источник
Я согласен с @iluxa
portforwardpodcast
1
Что если enum является членом класса (объекта), ожидаемым в качестве ввода в вызове rest?
жеребец
2

Строки.

Одной из сильных сторон Json является то, что он читается человеком. При отладке вывода через пол года "0" ничего вам не скажет.

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

Это превращается в голосование, хотя.

Evgeni
источник
1

Лучшая практика зависит от того, кто использует ваш API. Если вы пытаетесь облегчить жизнь потребителю, вы должны предоставить пример кода на C, JAVA, iOS, python, ruby, который может использовать ваш API. В этих оболочках вы можете включить enum, использовать int в json, а затем просто проанализировать ваш json в объект с уже установленным enum и вернуть этот объект в код пользователя.

Еще одна вещь, которую вы могли бы сделать, это предоставить оба. например:

{
  "name": "The name",
  "typeId": 0,
  "type": "ItemTypeBool"
   ...
}

Или вы можете использовать type и typeStr в зависимости от того, что выглядит лучше для вашего API.

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

Посмотрите на json здесь: https://dev.twitter.com/docs/api/1/get/search В Twitter есть пример предоставления избыточных данных (id и id_str), но это потому, что некоторые клиенты json не могут анализировать длинные целые числа из «число» в json и требует строку, чтобы избежать потери цифр

portforwardpodcast
источник