Soll ich beim Erstellen einer API bei kleinen Funktionen und vielen Aufrufen bleiben oder bei einigen Aufrufen und großen Funktionen?

Ich habe eine Schienenplattform, die ich pflege. Darauf sind viele verschiedene Webanwendungen aufgebaut. Jetzt fordert ein Client jedoch eine API an, damit die Benutzer auf ihrer Website bleiben, aber einige der automatisierten Aufgaben nutzen können, die wir haben.

Die Plattform wird zum Erstellen von Versicherungsanwendungen verwendet und ermöglicht deren Online-Kauf sowie das Herunterladen von Dokumentationen zu Ihrer Police.

Meine Frage beim Erstellen der API lautet also:

Wenn ich eine Menge Dinge zu tun haben, wie validate, erstellen user, user profileund policy, so ziemlich in der gleichen Zeit. Sollte ich 4 separate API-Aufrufe durchführen und den Client 4 Aufrufe auf seiner Seite erstellen lassen? ODER sollte ich einen einzigen Aufruf haben, der viele Parameter ausnimmt, den Client validiert und alle drei dieser Dinge gleichzeitig erstellt, um die Dinge für den Client zu vereinfachen?

In diesem Fall erhält der Client alle erforderlichen Informationen zur gleichen Zeit, sodass es nicht so ist, als ob in seiner Anwendung ein natürlicher Fluss stattfindet, in dem er pausiert, und er kann einen API-Aufruf an meine Plattform senden.

Nachdem ich schon viele APIs auf der Client-Seite verwendet habe, ist es mein Gedanke, es dem Client so einfach wie möglich zu machen und ihn nur einen Anruf tätigen zu lassen. Dies führt jedoch zu einer ziemlich großen functionsAPI, für die ich auch kein Fan bin.

Wie schlagen Sie vor, ich gehe das an?

Ich bin nicht sehr zuversichtlich, dass die Kunden eine komplizierte API auf ihrer Seite implementieren können.

Wie wäre es mit beidem? Verfügen Sie über eine " Low Level " -API (sozusagen), die Funktionen des Systems verfügbar macht, und über eine weitere "Ebene", die Dienste bereitstellt, die ein Client möglicherweise ausführen möchte. Diese Schicht würde die erforderlichen Low-Level-APIs verwenden, die jedoch weiterhin verfügbar sind, wenn der Client dies wünscht.

UPDATE: Um auch einige der großen Punkte und Kommentare von anderen zu enthalten.

1. Überlegen Sie, ob der Client jemals eine der kleineren API-Methoden aufrufen muss. Ist es beispielsweise möglich, createUserProfile aufzurufen, ohne auch createUser aufzurufen? Wenn nicht, dann machen Sie diese Methode nicht sichtbar. Vielen Dank, NoobsArePeople2

2. Ein einfacher, aber ausgezeichneter Punkt. Der entscheidende Punkt beim Anzeigen von Elementen in einer API ist, dass Sie sie niemals freigeben können. Setzen Sie das Minimum frei, das zum Funktionieren und Erweitern erforderlich ist, anstatt alles freizulegen, und ... na ja, dann kann es peinlich und umständlich sein, nackt Änderungen vorzunehmen . Danke MichaelT

Ich denke, Sie sehen es falsch. Mach dir keine Sorgen über große | kleine Anrufe oder viele | wenige Anrufe.

Denken Sie an die Geschäftsobjekte und die Aktionen, die mit | ausgeführt werden können für | gegen diese Objekte.

Du hast:

• Benutzer
• Richtlinien
• Preise
• ...

Daher sollten Sie API-Aufrufe für diese Objekte erstellen.

• User.Create
• User.UpdatePassword
• Policy.Validate
• ...

Die Idee ist, atomare oder atomnahe Operationen auf der Grundlage der Geschäftsobjekte und ihrer Aktionen zu erstellen. Dies vereinfacht das Design und die Codierung - Aufrufe, die genau das tun, was das Geschäftsobjekt tun soll, was dem mentalen Modell oder den Erwartungen der Programmierer entspricht. Wenn die Programmierer oder Architekten die Anforderungen mit den Geschäftsanalysten besprechen, können sie alle dieselbe Terminologie und denselben allgemeinen Ablauf verwenden.

Das Problem bei größeren All-in-One-Anrufen ist das Risiko von Nebenwirkungen. Wenn Policy.Create auch einen Benutzer erzeugt und eine andere Aktion auslöst, würde dies die Erwartungen der Programmierer sprengen. Ebenso zwingen viele kleine Aufrufe den Programmierer, sich daran zu erinnern, erst A und dann B und dann C aufzurufen, um eine "einzelne" Geschäftsoperation auszuführen.

Und wie Sie die Anrufe benennen, hängt davon ab, was Rails und Ihre unterstützenden Webservices unterstützen.

Dies führt zu einigen Aufrufen, die eine Reihe von Parametern benötigen und möglicherweise mehrere Aufrufe im Back-End haben, die für den Client verdeckt sind. Sie werden auch einige relativ schnelle / einfache Aufrufe haben, bei denen die API kaum mehr als ein Wrapper für die zugrunde liegende Routine ist.

Ich denke, Ihr Bauchgefühl ist richtig - machen Sie die API für Verbraucher einfach. In gewissem Maße ist dies die Philosophie hinter Consumer Driven Contracts .

Insbesondere sollte die API geeignete Geschäftsanwendungsfälle offenlegen. Betrachten Sie den Geschäftsbereich - besteht wirklich ein Bedarf für diese Funktionen auf niedriger Ebene? Was ist der Nachteil, wenn man sie einkapselt? Große Funktionen in der API sind an und für sich kein Problem. Ein Problem wäre, wenn eine große Funktion Vorgänge sequenziert, die möglicherweise partitioniert werden müssen, damit der Benutzer eingreifen kann.

Persönlich mag ich APIs, die:

1. sind so optimiert, dass gängige Use Cases einfach durchgeführt werden können
2. Aufrufe im Zusammenhang mit CRUD- Operationen sind stapelorientiert oder haben Stapelversionen
3. Ermöglicht Reflexion (damit Benutzer, die Plugins oder Bindungen für andere Computersprachen schreiben, den Prozess automatisieren können)