it-swarm.com.de

So stellen Sie (Aufzählungs-) Typen in einer öffentlichen API dar

Ich arbeite an einer einfachen API, die ich für meinen eigenen Kunden verwenden und in Zukunft für die Öffentlichkeit zugänglich machen möchte. Ich habe "Item" -Objekte, die verschiedene "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 Ganzzahlen oder als definierte "Zeichenfolgen" übertragen soll. Der JSON wäre:

Für ganze Zahlen:

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

Für Saiten:

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

Ich frage mich, ob es dafür eine bewährte Methode gibt. Das Beibehalten der Ganzzahl würde den Code leicht vereinfachen und die Bandbreite verringern, aber Zeichenfolgen wären für Entwickler leichter zu 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.

33
Julien

Stellen Sie die Zeichenfolgen bereit. Zahlen sind bedeutungslos. Sie verwenden sie nicht in Ihrem eigenen Code, richtig (Sie wickeln Enum-Werte um, das sind im Grunde Zeichenfolgen) - warum sollten Sie den Benutzer dafür bestrafen, dass Sie diese Zahlen verwenden müssen?

Der einzige Profi, wenn Sie die Zahlen offenlegen - einfacher für Sie, diese zu analysieren. Aber hey, wer kümmert sich um dich? Kümmere dich um die API-Clients.

Wenn Sie die Zeichenfolgen bereitstellen - einfacher für die Kunden; Ich werde niemals Dinge wie "4 wurde zugunsten von 17 veraltet" sagen müssen. etwas schwieriger in Ihrem Namen zu analysieren, aber das ist in Ordnung.

Geben Sie nicht beides an: Als Benutzer muss ich mich fragen

  • welches benutze ich Beide? [weiter zum Lesen von Dokumenten]
  • warum gibt es zwei Möglichkeiten, dasselbe zu sagen? sind sie subtil unterschiedlich? [weiter zum Lesen von Dokumenten]
  • was ist, wenn ich beide spezifiziere und eine Nichtübereinstimmung vorliegt? wird es sich beschweren? wird man Vorrang haben? welcher? [weiter zum Lesen von Dokumenten]

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

42
iluxa

Saiten.

Eine der Stärken von Json ist, dass es für Menschen lesbar ist. Wenn Sie die Ausgabe in einem halben Jahr debuggen, sagt "0" nichts aus.

Einige Frameworks führen auch eine automatische Konvertierung durch. Wenn Sie keinen verwenden, können Sie selbst einen Konverter erstellen, um Ihren Code trocken zu halten.

Dies führt jedoch zu einer Stimmabgabe.

2
Evgeni

Best Practice 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, Ruby, der Ihre API verbrauchen kann. Geben Sie in diese Wrapper die Aufzählung ein Verwenden Sie ein int in json und analysieren Sie dann Ihr json in ein Objekt mit der bereits festgelegten Aufzählung und geben Sie dieses Objekt an den Benutzercode zurück.

Sie können auch beides bereitstellen. 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 fest, dass diese redundant sind und der Entwickler entscheiden muss, welche für seine Anwendung am besten geeignet ist.

Schauen Sie sich den json hier an: https://dev.Twitter.com/docs/api/1/get/search Twitter hat ein Beispiel für die Bereitstellung redundanter Daten (id und id_str), aber dies liegt an einigen JSON-Clients können keine langen Ints von einer "Zahl" in JSON analysieren und benötigen eine Zeichenfolge, um den Verlust von Ziffern zu vermeiden

1