Come rappresentare i tipi (enum) in un'API pubblica

32

Sto lavorando a una semplice API che desidero utilizzare per il mio client e che sarà aperta al pubblico in futuro. Ho oggetti "Item" che possono avere diversi "tipi". Il tipo è un "typedef enum" C, per il momento ho:

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

(Potrei aggiungerne alcuni in futuro)

Mi chiedo se dovrei piuttosto trasferirlo come numeri interi o come "stringhe" definite. Il JSON sarebbe:

Per numeri interi:

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

Per archi:

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

Mi chiedo se ci sia una buona pratica per questo. Mantenere il numero intero semplificherebbe leggermente il codice e ridurrebbe la larghezza di banda, ma le stringhe sarebbero più facili da ricordare per gli sviluppatori. Ricordo di aver lavorato su un progetto e che dovevo ricordare 1 = immagine, 2 = audio, 3 = html, ... che non ha alcun senso.

Quindi ti sto chiedendo, se conosci qualche altro aspetto che dovrei considerare.

api patterns-and-practices enum

— Julien
fonte

Ti aspetti che i tuoi utenti modifichino JSON manualmente spesso?

— James,

39

Fornire le stringhe. I numeri non hanno significato. Non li usi nel tuo codice, giusto (stai avvolgendo i valori enum in giro, che sono fondamentalmente stringhe) - perché punire l'utente con dover usare questi numeri?

L'unico pro se esponi i numeri - più facile per te analizzarli. Ma hey, a chi importa di te. Prenditi cura dei client API.

Se si forniscono le stringhe - più facile per i clienti; non dovrò mai dire cose come "4 erano state deprecate a favore di 17"; analisi leggermente più difficile per tuo conto, ma va bene.

Non fornire entrambi: come utente, sono lasciato a chiedermi

quale uso? Tutti e due? [a leggere documenti]
perché ci sono due modi per dire la stessa cosa? sono leggermente diversi? [a leggere documenti]
cosa succede se specifico entrambi e non c'è corrispondenza? si lamenterà? si avrà la precedenza? quale? [a leggere documenti]

Come puoi vedere, mi stai facendo leggere molti documenti senza motivo.

— iluxa
fonte

Sono d'accordo con @iluxa

— portforwardpodcast l'

1

Cosa succede se enum è un membro della classe (oggetto) previsto come input nella chiamata di riposo?

— stallone

2

Stringhe.

Uno dei punti di forza di Json è che è leggibile dall'uomo. Quando esegui il debug dell'output tra sei mesi, "0" non ti dirà nulla.

Alcuni framework eseguiranno anche la conversione automatica. Se non ne usi uno, puoi creare tu stesso un convertitore per mantenere il codice asciutto.

Ciò si traduce in una votazione, tuttavia.

— Evgeni
fonte

1

Le migliori pratiche dipendono da chi sta consumando la tua API. Se stai cercando di rendere la vita facile per il consumatore, dovresti fornire un codice di esempio in C, JAVA, iOS, Python, Ruby che può consumare la tua API. In questi wrapper è possibile includere l'enum, utilizzare un int in json e quindi analizzare il proprio json in un oggetto con l'enum già impostato e restituire questo oggetto al codice degli utenti.

Un'altra cosa che potresti fare è fornire entrambi. per esempio:

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

Oppure puoi usare type e typeStr a seconda di ciò che sembra migliore per la tua API.

E quindi indicare chiaramente nella documentazione che questi sono ridondanti e spetta allo sviluppatore scegliere quale sia la migliore per la propria applicazione.

Guarda qui il json: https://dev.twitter.com/docs/api/1/get/search Twitter ha un esempio di fornitura di dati ridondanti (id e id_str), ma questo perché alcuni client JSON non riescono ad analizzare lunghi un "numero" in json e richiede una stringa per evitare di perdere cifre

— portforwardpodcast
fonte