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

Question

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

#1 da (33 voti)
#2 da (2 voti)
#3 da (0 voti)

27

Sto lavorando su una semplice API che voglio utilizzare per il mio cliente e ad aprirla al pubblico in futuro. Ho oggetti "Item" che possono avere "tipi" diversi. Il tipo è un C "typedef enum", per il momento ho:

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

(potrei aggiungerne alcuni in futuro)

Mi chiedo se preferirei trasferirlo come interi o come definiti "stringhe". Il JSON sarebbe:

Per numeri interi:

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

Per le stringhe:

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

Mi chiedo se esiste una best practice 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 che lavoravo a un progetto e dovevo ricordare 1 = image, 2 = audio, 3 = html, ... che non ha alcun senso.

Quindi ti chiedo, se conosci qualche altro aspetto che dovrei prendere in considerazione.

api patterns-and-practices enum

posta Julien 02.12.2013 - 21:58

fonte

3 risposte

2

Stringhe.

Uno dei punti di forza di Json è che è leggibile dall'uomo. Se esegui il debug dell'output a metà anno da questo momento, "0" non ti dirà nulla.

Anche alcuni framework eseguiranno automaticamente la conversione. Se non lo stai utilizzando, puoi creare autonomamente un convertitore per mantenere il tuo codice asciutto.

Tuttavia, si tratta di un lancio di voti.

risposta data 03.12.2013 - 18:19

fonte

0

La migliore pratica dipende da chi sta consumando la tua API. Se stai cercando di semplificarti la vita per il consumatore, dovresti fornire un codice di esempio in C, JAVA, iOS, python, ruby che possa consumare la tua API. In questi wrapper puoi includere l'enum, usare un int in json, e quindi solo analizzare il tuo 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 cosa è meglio per la tua API.

E poi indica chiaramente nella tua documentazione che questi sono ridondanti e spetta allo sviluppatore scegliere quale sia il migliore per la loro applicazione.

Guarda qui il json: link Twitter ha un esempio di fornitura di dati ridondanti (id e id_str), ma questo perché alcuni client json non riescono a parzializzare da un "numero" in json e richiedono una stringa per evitare di perdere cifre

risposta data 03.12.2013 - 01:22

fonte

Leggi altre domande sui tag api patterns-and-practices enum

Miglior approccio all'apprendimento della programmazione web [chiuso] Come risolvere la dipendenza circolare?

score 33 · Accepted Answer

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

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

Se fornisci le stringhe - più facile per i clienti; non dovrò mai dire cose del tipo "4 erano state deprecate a favore di 17"; parsing leggermente più difficile a tuo nome, ma va bene.

Non fornire entrambi: come utente, mi rimane da chiedermi

quale uso? Tutti e due? [on to reading docs]
perché ci sono due modi per dire la stessa cosa? sono sottilmente diversi? [on to reading docs]
E se specificassi entrambi e ci fosse una mancata corrispondenza? si lamenterà? avrà la precedenza? quale? [on to reading docs]

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