web-dev-qa-db-fra.com

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

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 souvenir de 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.

apipatterns-and-practicesenum
33
Julien

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 des documents]
  • pourquoi y a-t-il deux façons de dire la même chose? sont-ils subtilement différents? [sur la lecture des documents]
  • que faire 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 des documents]

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

42
iluxa

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.

2
Evgeni

Les meilleures pratiques dépendent de la personne qui consomme votre API. Si vous essayez de faciliter la vie du consommateur, vous devez fournir un exemple de code en C, Java, iOS, python, Ruby qui peut consommer votre api. Dans ces wrappers, vous pouvez inclure l'énumération , utilisez un int dans json, puis analysez simplement votre json dans un objet avec l'énumération déjà définie et renvoyez 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 les clients json ne peuvent pas analyser les entiers longs à partir d'un "nombre" dans json et nécessitent une chaîne pour éviter de perdre des chiffres

1
portforwardpodcast