Ich baue eine API, die ich im Laufe der Zeit aktualisieren möchte. Ist es sinnvoll, eine Versionsnummer als Argument in die API aufzunehmen?
Ich schreibe eine Schlüssel / Wertspeicher-API in Ruby, Java, Erlang und C #. Ich möchte etwas bauen, das erweiterbar ist, da ich weiß, dass es viele Dinge gibt, an die ich noch nicht gedacht habe, die in die Zukunft integriert werden müssen. Ich möchte jedoch wissen, ob es einen sauberen Weg dafür gibt und ob Versionsnummern dabei eine Rolle spielen.
Sie können es tun, es ist besser (IMHO), wenn Sie Ihre API nur abwärtskompatibel machen. Im Allgemeinen ist es einfacher, da Sie nicht auf Ihre Seite verzweigen müssen, sondern nur die angegebene Methode implementieren.
Ich nehme an, dass es wirklich ziemlich implementierungsspezifisch (und auch umweltspezifisch) ist. Ich würde tun, was am einfachsten / besser scheint.
Ich würde sagen, solange Sie die Rückwärtskompatibilität in irgendeiner Mode beibehalten, dann ist alles gut.
Das kann sinnvoll sein, wenn Sie eine objektorientierte API erstellen und die Versionsnummer einer Factory geben. Es ist auch in dynamischen datenzentrischen APIs üblich - Sie fragen die Bibliothek nach Daten und müssen angeben, welches Format / welche Version die Daten haben sollen.
Häufiger für "traditionelle" Bibliotheken (wie in denen, mit denen Sie in Ihren C / C ++ /. NET-Anwendungen verbunden sind) ist:
stellt eine API zum Abrufen der Versionsnummer der Bibliothek bereit. Dadurch kann die Anwendung entscheiden, ob sie eine neuere / ältere Version der Bibliothek benötigt.
ist so lange rückwärtskompatibel wie möglich.
Funktionen hinzufügen, nicht ändern. Wenn Sie Argumente / Eingabe hinzufügen oder Verhalten ändern müssen - erstellen Sie stattdessen eine neue Funktion und behalten Sie die alte Funktion bei.
Wenn Sie schließlich die Rückwärtskompatibilität abbrechen müssen und die alten Fehler loswerden müssen, nur um rückwärtskompatibel zu sein, müssen Sie ein vernünftiges Versionsschema haben, das eindeutig auf inkompatible Versionen hinweist.
Ich habe mehrere APIs verwendet, die eine Art von Versionsverwaltung unterstützen, insbesondere ODBC. Keiner von ihnen erlaubte die Versionierung auf API-Aufrufebene - sie alle verlangten von Ihnen, der Bibliothek mitzuteilen, mit welcher Version Sie einmal arbeiten wollten - etwas wie:
%Vor%Persönlich würde ich diesen Pfad möglichst vermeiden (mach deine neuen APIs rückwärtskompatibel) und sicher wäre die Versionierung auf der individuellen Anrufstufe nicht tolerierbar und nicht praktikabel. Stellen Sie sich Code wie:
vor %Vor%Sie können die Nichtübereinstimmung zum Zeitpunkt der Kompilierung nicht erkennen, und sie funktioniert möglicherweise nicht zur Laufzeit. Yechh!
Erstens, welche Art von API meinen Sie - eine Bibliothek, mit der Anwendungen verknüpft sind, oder eine XML / RPC-API? Ich werde das letztere in meiner Antwort annehmen.
Definitiv - nur so können Ihre API und / oder der Client unterscheiden, welche Methoden / Parameter ihnen zur Verfügung stehen. Es ermöglicht Ihnen auch, alte Clients mit einer neuen Version der API zu bedienen.
Etwas, das ich in der Vergangenheit gut gefunden habe, ist eine Form der Handshake-Methode, bei der der Client dem Server mitteilt, welche Version er erwartet. Der Server antwortet dann mit seiner aktuellen Version und kann optional entscheiden, diesen Client nicht zu unterstützen (so dass Sie eine ältere Version auslaufen lassen können, und sie dann später nicht mehr unterstützen müssen, sodass Clients aktualisiert werden müssen.)
Wie für eine Bibliothek sollten Sie auf jeden Fall eine Versionsnummer angeben, damit Anwendungen mit verschiedenen Versionen verknüpft werden können. Eine ältere Version kann auch dann verwendet werden, wenn eine neuere Version existiert, bis die Anwendung für die neue Version aktualisiert wurde / p>
Erstens ist es schwierig, spezifisch zu sein, ohne zu wissen, für welche Sprache Ihre API ist.
Ich denke, es wäre akzeptabel, beim Erstellen eines Objekts eine Versionsnummer zuzulassen. Damit können Sie ein Objekt MyApi der Version 1 oder Version 2 erstellen, wobei verschiedene Versionen des Objekts unterschiedliche Methoden haben. Es sollte weiterhin möglich sein, Objekte der Version 1 mit der API der Version 2 zu erstellen, so dass Benutzer der Bibliothek schrittweise upgraden können.
Ich glaube nicht, dass Sie Versionsnummern für Methoden oder Funktionsaufrufe versionieren sollten. Für mich scheint das Hinzufügen von Boilerplate zu jedem einzelnen Aufruf Ihrer API. In diesem Fall sollten Sie die Verwendung optionaler Parameter in Betracht ziehen, damit Sie die Kompatibilität und die veralteten Methoden bei Bedarf erweitern können.
Ja, das Zulassen von Versionsnummern in APIs ist vernünftig, aber ich würde die Weitergabe an eine einzelne Methode in einer MetaAPI beschränken, wodurch der Benutzer Ihrer API eine bestimmte Version davon abruft.
Verwenden Sie für jede Version eine andere Schnittstelle und ändern Sie sie nicht, sobald sie freigegeben wurde.
Dies macht die Rückwärtskompatibilität viel einfacher.
Ja, das ist sehr sinnvoll, besonders wenn Sie ein System verwenden, das auf Marshalling / Unmarshalling und Schnittstellen (COM / CORBA / SOAP) aufgebaut ist. Es ist sogar in monolithischen Anwendungen nützlich.
Allerdings ist dieser Ansatz für sehr komplizierte Software-Projekte geeignet, und wenn Sie es nicht brauchen, verwenden Sie es nicht - Sie können sich in einer unendlichen Version verewigen - Hölle.
bearbeiten: Vielleicht möchten Sie Apache Thrift (spärlich dokumentiert) für den Datenaustausch lesen oder Protokollpuffer (weniger Sprachen werden unterstützt)
Eine Sache, die Sie tun sollten, ist Funktionen zur Verfügung zu stellen, die Versionsnummern nehmen und ihnen Sinn machen. Funktionen wie:
%Vor%oder:
%Vor% (Ja, verwenden Sie #define für C und C ++, damit der Präprozessor auf der Version zur Kompilierungszeit arbeiten kann.)
Auf diese Weise wird Ihr Code in Ihren Versionsprüfungen nicht mit Magic Numbers geladen, und die Leute können Ihren Code lesen und wissen, nach welcher Funktion Sie wirklich suchen.
Tags und Links api