Wie dokumentiere ich Anforderungen für eine API systematisch?

Ich arbeite derzeit an einem Projekt, in dem ich die Anforderungen von zwei bestimmten IT-Systemen, die Cloud Computing verwenden, für eine Cloud-API analysieren muss. Mit anderen Worten, ich muss analysieren, welche Anforderungen diese Systeme an eine Cloud-API haben, damit sie diese wechseln und gleichzeitig ihre aktuellen Ziele erreichen können.

Lassen Sie mich ein Beispiel für einige informelle Anforderungen von Projekt A geben:

1. Beim Starten von virtuellen Maschinen in der Cloud über die API muss es möglich sein, die Speichergröße, den CPU-Typ, das Betriebssystem und einen SSH-Schlüssel für den Root-Benutzer anzugeben.
2. Es muss möglich sein, den eingehenden und ausgehenden Netzwerkverkehr pro Stunde und virtueller Maschine zu überwachen.
3. Die API muss die Zuweisung öffentlicher IPs zu einer virtuellen Maschine und das Abrufen der öffentlichen IPs unterstützen.
4. ...

In einer späteren Phase des Projekts werde ich einige Cloud-Computing-Standards analysieren, die Cloud-APIs standardisieren, um herauszufinden, wo mögliche Mängel in den aktuellen Standards bestehen. Eine Feststellung könnte und wird wahrscheinlich sein, dass ein bestimmter Standard die Überwachung der Ressourcennutzung nicht unterstützt und daher derzeit nicht verwendbar ist.

Ich versuche derzeit, einen Weg zu finden, meine Anforderungen systematisch aufzuschreiben und zu klassifizieren. Ich bin der Meinung, dass die Art und Weise, wie ich sie derzeit aufschreibe (wie die drei obigen Punkte), zu informell ist.

Ich habe einige Bücher über Anforderungsentwicklung und Softwarearchitektur gelesen, aber alle konzentrieren sich zu sehr auf Details und Implementierung. Ich kümmere mich wirklich nur um die Funktionen, die über die API / Schnittstelle bereitgestellt werden, und ich denke nicht, dass UML-Diagramme usw. die richtige Wahl für mich sind. Ich denke, dass die Anforderungen, die ich gesammelt habe, derzeit als User Stories beschrieben werden können. Aber reicht das bereits für eine differenzierte Anforderungsanalyse aus? Wahrscheinlich sollte ich "eine Ebene tiefer" gehen ...

Lesen Sie Dokumentieren von Softwarearchitekturen, zweite Ausgabe: Ansichten und darüber hinaus , Kapitel 7: Dokumentieren von Softwareschnittstellen.

Oder überprüfen Sie zumindest einige bekannte API-Dokumentationen wie die von Google ( Maps , GData - veraltet, aber komplex) von Amazon ( S3 ) oder die Dokumentation für Microsoft-Anwendungen und -Dienste, die auf MSDN (für Live-Dienste , aber auch für Windows ) zusammengestellt wurden.

Normalerweise besteht eine API-Dokumentation aus 3 Teilen:

• eine Übersicht darüber, wofür das Ding ist, was jemand daraus machen könnte, vielleicht eine architektonische Übersicht
• Ein Entwicklerhandbuch, in dem einige häufig verwendete Aufgaben mit der API erläutert werden, normalerweise mit Codebeispielen und herunterladbaren Beispielanwendungen.
• Eine API-Referenz, wie es funktionieren soll

Theoretisch - wenn wir an Brooks Mythical Man Month glauben - entwerfen Sie die Dokumentation und stellen sicher, dass es eine passende Implementierung gibt.

Nun zurück zum Üben

Das Entwerfen von Anforderungen für eine API erfolgt wie jedes Software-Design.

1. Sie tragen die verschiedenen Akteure ein , die die API verwenden sollen ( z. B. anhand eines Kontextdiagramms ).
2. Sie beschreiben die typischen Anforderungen jedes Akteurs an das System anhand von Anwendungsfällen
3. Für jeden Anwendungsfall entwickeln Sie eine Reihe von Szenarien, wie das imaginäre System verwendet werden soll (das Buch Schreiben effektiver Anwendungsfälle kann Ihnen dabei helfen).
4. Sie erstellen entweder Robustheitsdiagramme , Sequenzdiagramme oder Aktivitätsdiagramme , aber Sie entwerfen das Verhalten basierend auf den Szenarien , um herauszufinden, welche Nachrichten übergeben werden müssen
5. Aus den Nachrichten leiten Sie die zugrunde liegende Datenarchitektur ab , indem Sie sich ansehen , welche Parameter für die erfolgreiche Kommunikation jeder Nachricht erforderlich sind.

Viele Leute würden mit der zugrunde liegenden Datenstruktur beginnen, aber ich finde das albern: Bei Computern (und Objekten) geht es um Interaktionen. Sie müssen verstehen, was von beiden Seiten kommuniziert werden muss, um eine erfolgreiche Interaktion durchzuführen. Daten sind nur der Parameter dieser Interaktionen.

Normalerweise mache ich Aktivitätsdiagramme oder einfache Flussdiagramme, die die übergebenen Argumente als Objekte oder Klassen anzeigen. Das heißt, es gibt einen Kontrollfluss, aber wir sehen, welche Informationen eine der Parteien an die andere weitergegeben hat.

Nachdem Sie alle diese Schritte abgeschlossen haben, greifen Sie erneut zu Ihren Szenarien und beginnen mit der Erstellung von Abnahmetests . Das liegt daran, dass APIs von Computerclients verwendet werden sollen. Daher sollte Ihr erster Code ein Computerclient sein, der das automatische Abrufen als Test durchführt.

Abnahmetests werden entweder in der Form "bereitgestellte Eingabe" - "erwartete Ausgabe" oder als Code geschrieben. Sie können viele Bücher über BDD und TDD finden, die Ihnen erklären, wie man gute Tests schreibt.

Außerdem beginnen Sie hier, Bücher über REST-Schnittstellen und ähnliches herauszubringen, falls Sie eine Web-API erstellen , da Ihre Tests vom ersten Tag an ausführbar sein müssen .

Aus den Szenarien erstellen Sie auch Beispielcode und ein Entwicklerhandbuch.

Aus den Sequenzdiagrammen und Datenarchitekturdiagrammen entwickeln Sie die API-Referenz.

Fügen Sie eine Prise HTML hinzu, stellen Sie sicher, dass alle Tests bestanden sind und dass Ihre Anwendung schnell, sicher und robust genug ist, und lassen Sie uns loslegen!

(Ich weiß, das war wasserfallartig: Agil ist dasselbe, außer dass Sie immer nur einen winzigen Teil davon machen, z. B. ein paar Szenarien pro Sprint)

Sie müssen wirklich nicht "formeller" werden als das, was Sie haben. Sie schreiben es für Menschen zum Lesen und wahrscheinlich hauptsächlich für sich selbst. Denken Sie also daran. Mein einziger Vorschlag ist, es in eine Hierarchie zu setzen und es im Umrissformat zu nummerieren. Auf diese Weise können Sie in Bewertungen, Checklisten usw. eine Zahl wie 3.0.1 als Kurzform bezeichnen und leicht unterscheiden, wovon Sie sprechen.