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

32

Я працюю над простим API, який я хочу використовувати для власного клієнта і відкривати для публіки в майбутньому. У мене є об'єкти "Item", які можуть мати різні "типи". Тип - це "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

— Жульєн
джерело

Чи очікуєте, що ваші користувачі часто редагують JSON вручну?

— Джеймс

39

Наведіть рядки. Числа безглузді. Ви не використовуєте їх у власному коді, правильно (ви обволікаєте значення перерахунків навколо, це в основному рядки) - навіщо карати користувача за необхідність використовувати ці цифри?

Єдиний професіонал, якщо ви виставляєте цифри, - вам простіше розібрати їх. Але ей, хто дбає про тебе. Подбайте про клієнтів API.

Якщо ви надаєте рядки - простіше для клієнтів; ніколи не доведеться говорити такі речі, як "4 застаріли на користь 17"; трохи складніше розбиратися від вашого імені, але це добре.

Не надайте і те і інше: як користувач, мені залишається цікаво

який я використовую? Обидва? [читати документи]
чому є два способи сказати одне і те ж? вони тонко різні? [читати документи]
що робити, якщо я вказую і те, і невідповідність? буде скаржитися? хтось матиме перевагу? який? [читати документи]

Як бачите, ви змушуєте мене без жодних причин читати багато документів.

— ілюкса
джерело

Я згоден з @iluxa

— portforwardpodcast

1

Що робити, якщо enum - член класу (об'єкта), який очікується як вхід у виклик відпочинку?

— жеребець

2

Струни.

Одним із сильних сторін Джсона є те, що його читають людиною. При налагодженні результатів через півроку "0" нічого не скаже.

Деякі рамки також здійснюватимуть автоматичне перетворення. Якщо ви не використовуєте його, ви можете створити конвертер самостійно, щоб зберегти код.

Це, однак, перетворюється на голосування.

— Євгеній
джерело

1

Найкраща практика залежить від того, хто споживає ваш API. Якщо ви намагаєтеся полегшити життя споживачеві, вам слід надати зразок коду в C, JAVA, iOS, python, ruby, який може споживати ваші api. У ці обгортки ви можете включити enum, використовувати int в json, а потім просто розібрати свій json в об’єкт із уже встановленою enum та повернути цей об’єкт у код користувачів.

Ще одна річ, яку ви могли зробити - це забезпечити і те, і інше. наприклад:

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

Або ви можете використовувати type та typeStr, залежно від того, що найкраще виглядає для вашої програми.

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

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

— portforwardpodcast
джерело