Darstellen von (Aufzählungs-) Typen in einer öffentlichen API

32

Ich arbeite an einer einfachen API, die ich für meinen eigenen Kunden verwenden und in Zukunft der Öffentlichkeit zugänglich machen möchte. Ich habe "Item" -Objekte, die unterschiedliche "Typen" haben können. Der Typ ist ein C "typedef enum", für den Moment habe ich:

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

(Ich kann einige in der Zukunft hinzufügen)

Ich frage mich, ob ich es lieber als ganze Zahlen oder als definierte "Strings" übertragen soll. Der JSON wäre:

Für ganze Zahlen:

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

Für Streicher:

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

Ich frage mich, ob es hierfür eine bewährte Methode gibt. Das Beibehalten der Ganzzahl würde den Code etwas vereinfachen und die Bandbreite verringern, aber Strings könnten sich die Entwickler leichter merken. Ich erinnere mich, dass ich an einem Projekt gearbeitet habe und mich an 1 = Bild, 2 = Audio, 3 = HTML, ... erinnern musste, was keinen wirklichen Sinn ergibt.

Ich frage Sie also, ob Sie einen anderen Aspekt kennen, den ich berücksichtigen sollte.

api patterns-and-practices enum

— Julien
quelle

Erwarten Sie, dass Ihre Benutzer JSON häufig manuell bearbeiten?

— James

39

Stellen Sie die Saiten bereit. Zahlen sind bedeutungslos. Sie verwenden sie nicht in Ihrem eigenen Code, oder? (Sie setzen Enum-Werte ein, die im Grunde genommen Zeichenfolgen sind.) Warum sollten Sie den Benutzer damit bestrafen, diese Zahlen verwenden zu müssen?

Der einzige Profi, wenn Sie die Zahlen offenlegen - einfacher für Sie, diese zu analysieren. Aber hey, wen interessiert das schon. Kümmere dich um die API-Clients.

Wenn Sie die Zeichenketten zur Verfügung stellen - einfacher für die Klienten; Ich werde nie sagen müssen, dass Dinge wie "4 zugunsten von 17 abgelehnt wurden"; etwas schwieriger für Sie zu analysieren, aber das ist in Ordnung.

Nicht beides: Als Benutzer muss ich mich fragen

welches verwende ich? Beide? [weiter zum Lesen von Dokumenten]
warum gibt es zwei möglichkeiten, dasselbe zu sagen? Unterscheiden sie sich auf subtile Weise? [weiter zum Lesen von Dokumenten]
Was ist, wenn ich beides spezifiziere und eine Nichtübereinstimmung vorliegt? Wird es sich beschweren? Wird man Vorrang haben? welcher? [weiter zum Lesen von Dokumenten]

Wie Sie sehen, lassen Sie mich ohne Grund viele Dokumente lesen.

— iluxa
quelle

Ich stimme @iluxa

— portforwardpodcast zu

1

Was ist, wenn enum als Eingabe im rest-Aufruf ein Mitglied der Klasse (Objekt) erwartet?

— Hengst

2

Streicher.

Eine der Stärken von Json ist, dass es für Menschen lesbar ist. Beim Debuggen der Ausgabe sagt "0" in einem halben Jahr nichts.

Einige Frameworks werden auch automatisch konvertiert. Wenn Sie keinen verwenden, können Sie selbst einen Konverter erstellen, um Ihren Code trocken zu halten.

Dies führt jedoch zu einer Stimmabgabe.

— Evgeni
quelle

1

Die empfohlene Vorgehensweise hängt davon ab, wer Ihre API verwendet. Wenn Sie versuchen, dem Verbraucher das Leben zu erleichtern, sollten Sie Beispielcode in C, JAVA, iOS, Python und Ruby bereitstellen, der Ihre API verbrauchen kann. In diesen Wrappern können Sie die Aufzählung einschließen, ein int in json verwenden und dann Ihren json in ein Objekt mit der bereits festgelegten Aufzählung analysieren und dieses Objekt an den Benutzercode zurückgeben.

Eine andere Sache, die Sie tun könnten, ist, beide zur Verfügung zu stellen. zum Beispiel:

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

Oder Sie können type und typeStr verwenden, je nachdem, was für Ihre API am besten aussieht.

Stellen Sie dann in Ihrer Dokumentation klar, dass diese redundant sind und es dem Entwickler überlassen ist, die für seine Anwendung am besten geeignete zu wählen.

Schauen Sie sich den JSON-Code hier an: https://dev.twitter.com/docs/api/1/get/search Twitter bietet ein Beispiel für die Bereitstellung redundanter Daten (id und id_str) eine "Zahl" in JSON und erfordern eine Zeichenfolge, um den Verlust von Ziffern zu vermeiden

— portforwardpodcast
quelle