Comment représenter (énumérer) les types dans une API publique

32

Je travaille sur une API simple que je souhaite utiliser pour mon propre client et ouvrir au public à l'avenir. J'ai des objets "Item" qui peuvent avoir différents "types". Le type est un C "typedef enum", pour l'instant j'ai:

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

(Je pourrais en ajouter à l'avenir)

Je me demande si je devrais plutôt le transférer sous forme d'entiers ou de "chaînes" définies. Le JSON serait:

Pour les entiers:

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

Pour les cordes:

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

Je me demande s'il existe une meilleure pratique pour cela. Garder l'entier simplifierait légèrement le code et réduirait la bande passante, mais les chaînes seraient plus faciles à retenir pour les développeurs. Je me souviens avoir travaillé sur un projet, et je devais me rappeler 1 = image, 2 = audio, 3 = html, ... ce qui n'a pas vraiment de sens.

Je vous demande donc si vous connaissez un autre aspect que je devrais considérer.

api patterns-and-practices enum Julien
la source
Vous attendez-vous à ce que vos utilisateurs modifient souvent le JSON manuellement?
James

Réponses:

39

Fournissez les cordes. Les chiffres n'ont pas de sens. Vous ne les utilisez pas dans votre propre code, à droite (vous encapsulez des valeurs d'énumération, qui sont essentiellement des chaînes) - pourquoi punir l'utilisateur d'avoir à utiliser ces chiffres?

Le seul pro si vous exposez les chiffres - plus facile pour vous de les analyser. Mais bon, qui se soucie de toi. Prenez soin des clients API.

Si vous fournissez les chaînes - plus facile pour les clients; n'aura jamais à dire des choses comme "4 ont été dépréciés en faveur de 17"; analyse un peu plus difficile en votre nom, mais ça va.

Ne fournissez pas les deux: en tant qu'utilisateur, je me demande

  • lequel utiliser? Tous les deux? [sur la lecture de documents]
  • pourquoi y a-t-il deux façons de dire la même chose? sont-ils subtilement différents? [sur la lecture de documents]
  • que se passe-t-il si je spécifie les deux et qu'il y a un décalage? va-t-il se plaindre? aura-t-on priorité? laquelle? [sur la lecture de documents]

Comme vous pouvez le voir, vous me faites lire beaucoup de documents sans raison.

iluxa
la source
Je suis d'accord avec @iluxa
portforwardpodcast
1
Que faire si l'énumération est membre de la classe (objet) attendue comme entrée dans l'appel de repos?
étalon
2

Cordes.

L'une des forces de Json est qu'elle est lisible par l'homme. Lors du débogage de la sortie dans six mois, "0" ne vous dira rien.

Certains frameworks effectueront également la conversion automatique. Si vous n'en utilisez pas, vous pouvez créer vous-même un convertisseur pour garder votre code au sec.

Cela se traduit par un vote, cependant.

Evgeni
la source
1

Les meilleures pratiques dépendent de la personne qui consomme votre API. Si vous essayez de faciliter la vie du consommateur, vous devez fournir des exemples de code en C, JAVA, iOS, python, ruby ​​qui peuvent consommer votre api. Dans ces wrappers, vous pouvez inclure l'énumération, utiliser un int dans json, puis analyser simplement votre json dans un objet avec l'énumération déjà définie et renvoyer cet objet au code utilisateur.

Vous pouvez également fournir les deux. par exemple:

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

Ou vous pouvez utiliser type et typeStr en fonction de ce qui convient le mieux à votre API.

Et puis indiquez clairement dans votre documentation qu'ils sont redondants et qu'il appartient au développeur de choisir celui qui convient le mieux à leur application.

Regardez le json ici: https://dev.twitter.com/docs/api/1/get/search Twitter a un exemple de fourniture de données redondantes (id et id_str), mais cela parce que certains clients json ne peuvent pas analyser les entiers longs de un "nombre" en json et nécessite une chaîne pour éviter de perdre des chiffres

portforwardpodcast
la source