Was ist das beste API-Design für eine nicht-einfallsreiche Route mit Verschachtelung

Question

Ich schreibe eine API in Rails, die Preise für ein Paket von mehreren Fluggesellschaften abruft. Ein Paket wird universell in Bezug auf Abmessungen, Gewicht, Adresse und Adresse beschrieben. Jeder Spediteur hätte spezifische Details (FedEx: Kontonummer, Paketoptionen; USPS: Bearbeitbarkeit, Vorsortierung; UPS: Benachrichtigungsdetails usw.). Ich entscheide immer noch, ob ich den Preis lokal speichern oder von den offiziellen APIs abrufen soll.

Meine erste Frage ist über die Preis Ressource. Ich habe einen Preis Modell, aber es erbt nicht von ActiveRecord, da ich keine Preise Tabelle habe. Ich denke, dass meine URL wie /api/v1/preise aussehen würde und es würde eine Nutzlast wie { "length" : 1.0, "address_from" : ... } nehmen. Sollte dies ein POST oder ein GET sein? Ich vermute ein GET, da ich nicht wirklich eine Ressource erstelle, aber ich bin mir nicht sicher.

Meine zweite Frage betrifft die Nutzlast. Soll ich die trägerspezifischen Daten verschachteln? Mit anderen Worten, welcher Weg sieht korrekter aus (aus einer REST-Sicht und aus Sicht der Benutzerfreundlichkeit)? 1
Option:

{ "length" : 1.0, ..., "carrier" : { "name" : "FedEx", "account_number" : "123ABC", "package_options" : "XXX", ... } } 

Option 2:

{ "length" : 1.0, ..., "carrier" : "FedEx", "fedex_account_number" : "123ABC", "fedex_package_options" : "XXX", ... } 

Wenn es Option 1, sollte ich eine Art von Ressource Verschachtelung schaffen und sollte ich meine URL konstruieren ändern?

Answer 1

Ich entscheide immer noch, ob ich den Preis lokal speichern oder von den offiziellen APIs abrufen soll.

Wirklich gute Frage. Was ist, wenn sich der Preis in der Zukunft ändert? Ist Ihre App vom Preis zum Zeitpunkt des API-Aufrufs abhängig? Wenn ja, sollten Sie es auf jeden Fall lokal speichern, da der Preis von API-Aufruf zu API-Aufruf variieren kann. Im Zweifelsfall würde ich diesen Wert speichern, damit Sie später einen Papierpfad für Prüfungszwecke haben.

Ich stimme zu, dass /api/v1/prices eine GET-Anforderung erhalten sollte, da Sie keine Ressource erstellen, weder in Ihrer DB noch auf einem Remote-Dienst/API. Aber ist das eine Singular- oder Plural-Ressource? Wenn es Singular ist, sollten Sie in Betracht ziehen, /api/v1/price zu verwenden. Ob Sie den Preis id Teil der URL oder als Extra-Parameter machen, liegt ganz bei Ihnen.

Ich bevorzuge den Stil von Option 1, da das JSON-Format die zugrunde liegenden Modellbeziehungen beibehält. Dies macht es nicht einfacher zu verwenden und auch "selbstbeschreibend", da das Format der Daten auch seine Struktur kommuniziert. Es erfordert auch keine Analyse der JSON-Schlüssel.