R016 Beilage 3: Die Technische Servicebeschreibung

Transkript

1 Eidgenössisches Finanzdepartement EFD Informatiksteuerungsorgan des Bundes ISB R016 Beilage 3: Die Technische Servicebeschreibung Ausgabedatum: Version: 2.01 Status: Genehmigt Ersetzt: 1.0

2 Inhaltsverzeichnis 1 Einleitung Anwendungsgebiet Erläuterungen zur Nutzung Die Technische Servicebeschreibung Eindeutige Identifikation der Serviceversion Das technische Interface detaillierte Beschreibung Funktionalität Syntax und Semantik Dokumentation des technischen Kanals zum Bezug der Serviceversion Dokumentation der benutzten Datentypen Testfälle und Testdaten Dokumentation pro Testfall Dokumentation der Testdaten Nichtfunktionale (Grund-)Eigenschaften der Serviceversion Weitere technische Dokumentation Anhänge A. Referenzen /11

3 1 Einleitung 1.1 Anwendungsgebiet Die technische Servicebeschreibung enthält die Informationen, welche die Entwickler brauchen, welche den Service aus ihren Anwendungen heraus aufrufen möchten, und IT-Leistungserbringer, welche Lösungen betreiben, welche den Service nutzen. Diese Richtlinie gibt nur die Inhalte vor, nicht die Form. Es können daher unterschiedlichste Hilfsmittel für die Erstellung eingesetzt werden. So ist es beispielsweise möglich, technische Servicebeschreibungen teilweise oder ganz automatisch zu generieren (etwa aus UML Modellen oder aus WSDL Files). 1.2 Erläuterungen zur Nutzung Für das Verständnis dieses Dokuments ist es wie auch bei der fachlichen Servicebeschreibung wichtig zu verstehen, dass Services auf Basis unterschiedlicher Technologien entwickelt werden können. Je nach Anwendungsgebiet mag die eine oder die andere Technologie (z.b. Webservices, REST) vorteilhaft sein. Die vorliegende Richtlinie ist von dieser Technologiefrage unabhängig. Daher ist es notwendig, auch die Struktur der Servicebeschreibung unabhängig von bestimmten Technologien festzulegen. Dies spielt für praktisch alle realen Services eine Rolle, da ein fachlicher Service fast immer mehrere technische Funktionalitäten umfasst, die im Zusammenhang beschrieben werden müssen. Dazu kommt, dass im Laufe des Lebenszyklus eines Service oft verschiede Versionen von technischen Funktionalitäten sowohl parallel aus auch nacheinander zum Einsatz kommen können. Konkrete Nutzungshinweise: o Es ist möglich, die technische Servicebeschreibungen teilweise oder vollständig automatisch zu generieren, z.b. aus UML Modellen oder aus WSDL Files. o Gelegentlich kann ein Einzelservice in unterschiedlichen Varianten vorliegen. In diesem Fall sind die Varianten wie unterschiedliche Einzelservices zu dokumentieren und die Zusammengehörigkeit über andere Mittel (z.b. in der Namensgebung) aufzuzeigen. o Evtl. ist die Dokumentation anderswo im Web zugänglich abgelegt. In diesem Fall kann über Link darauf verwiesen werden. Anmerkung: Erläuterungen zur logischen Struktur eines Services aus fachlicher und technischer Sicht siehe [Services beim Bund]. 3/11

4 2 Die Technische Servicebeschreibung Die technische Servicebeschreibung bezieht sich auf eine Serviceversion! 2.1 Eindeutige Identifikation der Serviceversion Name, Version und URI müssen für jede in der Servicebeschreibung dokumentierte Serviceversion definiert werden. Zusätzlich ist noch die Angabe einer Service URI zur eindeutigen Identifikation notwendig. Service Name Service Version Service URI Eindeutiger Name, wie in der fachlichen Servicebeschreibung Version der Form X.Y, wie in der fachlichen Servicebeschreibung Eindeutige URI zur Identifikation des Services (und zur allfälligen Verwendung in XML-Dokumenten) entsprechend der [Namenskonventionen] 1,2. Beispiel: ManageSurfaceData/updateSurfaceDataForFarm/1 2.2 Das technische Interface detaillierte Beschreibung Die Servicefunktionalitäten müssen pro Interface exakt beschrieben werden. Wie genau diese strukturiert sind und mit den Servicefunktionalitäten zusammenhängen ist technologieabhängig. Bei Webservices gibt es pro Serviceoperation ein Interface, bei REST Services eines pro Service-URI. Eine hierarchische Gliederung der Funktionalitäten im Dokument sollte in der Servicebeschreibung verwendet werden, wenn sie den technischen Gegebenheiten entspricht und fachlich nachvollziehbar ist. Entsprechend kann die detaillierte Strukturierung der Beschreibung bei WMS (Web Map Service) und WFS (Web Feature Service) abweichen Grundsätzlich kann immer bei bestehender Dokumentation mit Referenzen gearbeitet werden Funktionalität Es wird zuerst eine Auflistung der Einzelfunktionalitäten dargestellt. Dazu gehört der exakte Ablauf der Funktionalität mit Vor-, Nach- und möglichen Fehlerbedingungen. Die Sprache der Beschreibung muss exakt sein und sich an Softwareentwickler richten. 1 Wichtig ist hier, dass nur die Major Version in die URI zur Identifikation aufgenommen wird, um zu garantieren dass ein Consumer Nachrichten von verschiedenen Minor Versionen verarbeiten kann. 2 Die URI dient der Identifikation und ist primär einfach als eindeutige Bezeichnung zu sehen. Es ist darüber hinaus möglich, die durch die URI identifizierte Ressource auch im Inter- oder Intranet abzulegen. Die Entscheidung darüber ist aber nicht im Scope dieses Dokumentes. 4/11

5 Name der Einzelfunktionalität (bei Webservices Service-operation) Version (optional) Zugehörigkeit / Gruppierung (optional) Verhalten Vorbedingungen Nachbedingungen Fehler Eindeutiger Name als String ohne Sonderzeichen Versionsangabe, falls die Einzelfunktionalität unabhängig vom Service versioniert werden kann (Frage der Technologie und der Strukturierung). Zugehörigkeit der Einzelfunktionalität zu einer logischen Gruppierung (z.b. porttype oder service bei Webservices). Detaillierte Beschreibung der Funktionalität, ggf. des zeitlichen Ablaufs der einzelnen Aktionen. Vorbedingungen für die Ausführung. Beschreibung des Zustandes nach erfolgreicher Ausführung Dokumentation aller möglichen (fachlichen 3 ) Fehler inkl. eindeutiger Bezeichnung, Nummer und Fehlermeldung Syntax und Semantik Grundlegend für die Beschreibung des Interfaces einer Einzelfunktionalität ist die Festlegung der logischen Struktur des Nachrichtenaustausches zwischen Consumer und Provider. Die Angabe ist optional und kann technologieabhängig sein. Eine best practice ist die Unterscheidung der folgenden Message Exchange Patterns, es dürfen aber auch andere verwendet werden: Request / Response, synchron Oneway (Request only, fire-and-forget), asynchron Request / Multiple Responses, asynchron Publish / Subscribe Alle Parameter der ein- und ausgehenden Nachrichten (Messages) müssen detailliert in Punkte Syntax (Name, Datenformat) und Semantik (Fachliche Bedeutung) beschrieben werden. Es gibt pro Service Operation je nach verwendetem Message-Exchange Pattern eine eingehende Nachricht Request, ausgehende Nachrichten Response bzw. auch Fault (für Fehler). Diese Darstellung ist kanalunabhängig, also unabhängig von der technischen Realisierung und dem verwendeten technischen Protokoll. Die bei den Fault-Nachrichten verwendeten Datenstrukturen sollten im Kontext von Departements, Ämtern oder grossen Projekten standardisiert werden. Wenn es die Verständlichkeit erfordert, darf die Darstellung an spezielle Kanäle angepasst werden, sofern die hier geforderten Informationen enthalten sind. Beispiel: Falls Webapplikationen mit HTML Formularen als Kanal verwendet werden, so ist es sinnvoll diese Formulare der Dokumentation der Datenstrukturen beizufügen; ebenso sollten dann zusätzlich zu den Eingabefeldern auch Buttons dokumentiert werden. 3 Ein fachlicher Fehler ergibt sich aus dem Algorithmus und ist eine eindeutige Konsequenz einer fehlerhaften Eingabe bzw. der Kombination von Eingabe und Vorbedingungen. Im Gegensatz dazu ist ein technischer Fehler nicht vorhersehbar und hat nichts mit einer bestimmten Eingabe zu tun. Beispiel: Datensatz nicht gefunden vs. Datenbank nicht erreichbar. 5/11

6 Es müssen die in den Nachrichten verwendeten komplexen Datentypen separat dokumentiert werden (siehe Abschnitt 0). Dokumentation Request Message: Parameter Name Datentyp Kardinalität Beispielparameter string 1 Dient als Beispiel Fachliche Bedeutung / Semantik Dokumentation Response Message: Parameter Name Datentyp Kardinalität Fachliche Bedeutung / Semantik Beispielparameter Beispieltyp (komplex) 0..1 Dient als Beispiel Dokumentation Fault (Fehler) Message: Parameter Name Type Kardinalität Fachliche Bedeutung / Semantik Beispielparameter Beispielfehlertyp (komplex) 1..* Dient als Beispiel 2.3 Dokumentation des technischen Kanals zum Bezug der Serviceversion Es muss angegeben werden, über welchen konkreten technischen Kanal der Service bezogen werden kann bzw. bezogen werden können soll. Dies muss ergänzt werden durch die Darstellung der kanalspezifischen technischen Interfacebeschreibungen, soweit diese vorhanden und zur Realisierung eines Consumers notwendig sind. Es kann je nach verwendetem Kanal davon mehrere geben. Beispiel: WSDL und XML Schema Dokumente für Webservices. Bezeichnung des Kanals Technische Interfacebeschreibung Logischer Endpunkt Eindeutige technische Bezeichnung des verwendeten Kanals: Protokoll, Standards, etc. Referenz auf externe Dokumente oder eingefügte Dokumente. Logischer Endpunkt, also eine kanalspezifische Darstellung einer Adresse, unter der der Service technisch aufgerufen werden kann. Dieser Endpunkt ist eine URI, aber in der Regel nicht identisch mit der eindeutigen URI zur Serviceidentifikation. Anmerkung: Ein Service kann auch mehrere Endpunkte haben, z.b. bei Verteilung über mehrere Rechenzentren. 6/11

7 Anmerkung: Zur Reduktion der Komplexität gehen wir hier vom Normalfall aus, dass es genau einen technischen Kanal pro Serviceversion gibt, wohl wissend, dass es diesbezüglich auch Ausnahmen geben kann, z.b. das anbieten eines Services über RMI/IOP und als Webservice. 2.4 Dokumentation der benutzten Datentypen Es müssen alle in den Interfacebeschreibungen verwendeten komplexen Datentypen in Punkto Syntax (Name, Datenformat) und Semantik (fachliche Bedeutung insbesondere der komplexen Typen) definiert werden. Liegt die Beschreibung der Datentypen in anderswo vor, kann darauf referenziert werden. Datentyp Beispieltyp: Detaillierte Beschreibung des Datentypen mit allen seinen Attributen und seinen Relationen zu anderen Datentypen. Wichtig ist, dass alle Abhängigkeiten (also Datentypen, die als Attribute wieder komplexe Typen haben) komplett dokumentiert werden. Ebenso ist zu vermerken, wenn Datentypen Spezialisierungen / Generalisierungen anderer Typen darstellen. Attribut Name Datentyp Kardinalität Beispielattribut Integer 1 Dient als Beispiel Fachliche Bedeutung / Semantik Aufzählung benutzter primitiver Datentypen: Eine Aufzählung und ggf. Beschreibung aller in Nachrichten genutzten einfachen (primitiven) Datentypen (wie string, date, boolean,...) sollte erfolgen. Dies macht vor allem dann Sinn, wenn die benutzten Typen nicht allgemein verständlich sind oder für bestimmte Technologien spezifische Ausprägungen besitzen. Primitiver Typ Integer UnsignedInteger Beschreibung Ganzzahl Positive Ganzzahl inkl. der Null 2.5 Testfälle und Testdaten Es sollen die für vollständige fachliche Tests von Service Consumern und Service Providern notwendigen Tests dokumentiert werden. Es können darüber hinaus Werkzeuge und Hilfen für leichteres Testen zur Verfügung gestellt werden. 7/11

8 Es ist eine Beschreibung aller Testfälle, die für einen vollständigen Test einer Implementierung (Service Provider) für die dokumentierte Serviceversion notwendig sind Dokumentation pro Testfall Für jeden Testfall muss dessen Zweck / Funktion sowie eingehende Daten (d.h. eine Request Message als XML Dokument) und das erwartete Verhalten dokumentiert werden. Falls die Serviceoperation eine Response Message erzeugt, kann diese das erwartete Verhalten dokumentieren. Bezeichnung Testfall Kurzbeschreibung Eingehende Daten Erwartetes Verhalten und ausgehende Daten Dokumentation der Testdaten Fachliche und technische Beschreibung der den Testfällen zugrunde liegenden Testdaten. Optionale Testdaten als XML-Dokumente oder in einer anderen technisch verwendbaren Form, ggf. auch in binärer Form als Attachment oder zum Download. Informationen für die praktische Durchführung von Tests: URI für Testressourcen URI für Testprovider Optionale Angabe einer URI, unter der ein Entwickler Dokumente, Testdaten bzw. Tools / Skripts anrufen kann. Wenn es einen simulierten Service Provider gibt, dann ist die optionale Angabe einer URI (auf der dieser läuft) notwendig, gegen den Service Consumer getestet werden können. Dieser simulierte Provider sollte analog der beschriebenen Testfälle auf die jeweiligen Test-Requests die erwarteten Antworten senden. 8/11

9 2.6 Nichtfunktionale (Grund-)Eigenschaften der Serviceversion Die nichtfunktionalen Grundeigenschaften gelten für die Serviceversion unanhängig von den speziellen Anforderungen einzelner Consumer, die in speziellen Service Kontrakten zu definieren wären. Wird eine Serviceversion speziell für einen ersten Consumer entwickelt, so können dessen Anforderungen zu Grundeigenschaften werden. Es müssen die nichtfunktionalen Grundanforderungen an den Service in der Servicebeschreibung dokumentiert werden. Diese müssen für jede Operation dokumentiert werden bzw. die Besonderheiten einzelner Operationen beschrieben werden. Dabei sind die nichtfunktionalen Grundanforderungen nach der im Folgenden dargestellten Systematik zu strukturieren. Access Control Data Security Performanz und Verfügbarkeit Hier geht es um die Identifikation von Nutzern (Authentisierung) und deren Autorisierung für die Nutzung von Services (grobgranulare Autorisierung). Der Umgang mit bereits bekannten Identitäten (Weiterleitung, Federation) muss ebenfalls hier beschrieben werden. User Authentisierung (Username & Passwort, Zertifikat, keine) Rollenbasierte Autorisierung, grobgranulare Autorisierung im Service Bus (benötigt, nicht benötigt) Token-basierte Weiterleitung von Identitäten (SAML, Kerberos, anderer Standard, nicht benötigt) Die benutzten technischen Standards müssen dokumentiert werden IP Schutzmechanismen (IPsec) Hier geht es um Eigenschaften bezüglich Sicherheit der transportierten Daten in Bezug auf unautorisiertes Lesen bzw. unautorisierte Veränderung. Die Massnahmen dagegen sind Verschlüsselung bzw. Signatur und können sowohl auf der Ebene der Nachrichten (unabhängig vom technischen Transportprotokoll) oder aber auf der Transportebene angewendet werden. Auch eine Kombination aus beiden Alternativen kann sinnvoll sein. Message-Level Security (Keine spezifische Sicherheit, Signatur, Signatur & Verschlüsselung) Transport-Level Security (Keine spezifische Sicherheit, Signatur, Signatur & Verschlüsselung) Die benutzten technischen Standards müssen dokumentiert werden Hier werden die Eigenschaften bezüglich Verfügbarkeit und Performanz eines Services dargestellt. Da es nicht einfach nur eine einzige Kenngrösse gibt, die Performanz beschreibt, werden hier sowohl Durchsatz als auch Nachrichtengrössen im Durchschnitt und in der Spitze dargestellt. Ebenso müssen 9/11

10 Zuverlässiges (Reliable) Messaging besondere temporäre Verteilungen der benötigten Performanz beschrieben werden. Durchschnittliche End-to-End Response Time 4 Durchschnittliche Nachrichtengrösse Durchschnittlicher Nachrichtendurchsatz Maximal vertretbare End-to-End Response Time Time-out erzeugen nach Peak Nachrichtengrösse Peak Nachrichtendurchsatz Benötigte Verfügbarkeit Wartungsfenster Zeitliche Variation der Servicenutzung Hier werden die Eigenschaften bezüglich garantierte Zustellung von Nachrichten und an die garantierte Bewahrung der Reihenfolge von Nachrichten dargestellt. Dies ist insbesondere dann notwendig, wenn das zugrundeliegende Transportprotokoll dies nicht von sich aus unterstützt (z.b. bei Webservices über HTTP). Bewahrung der Reihenfolge von Nachrichten (Benötigt / nicht benötigt) Garantierte Auslieferung (nach BestEffort, AtMostOnce, AtLeastOnce, ExactlyOnce) 2.7 Weitere technische Dokumentation Zusätzlich zur eigentlichen Servicebeschreibung können optional weitere technische Dokumente, etwa zur Darstellung der tech. Architektur oder des Systemumfeldes, der Servicebeschreibung beigelegt werden. Dies ist aber explizit optional. 4 Hier muss die Zeit für den Nachrichtentransport zum und vom Endpunkt ggf. herausgerechnet werden, da diese in vielen Szenarien (z.b. Internet) prinzipiell nicht garantiert werden kann. 10/11

11 Anhänge A. Referenzen [R016 Beilage 1] [R016 Beilage 4] Standard R016 Beilage 1: Services beim Bund Standard R016 Beilage 4: SOA-Namenskonventionen [R016 Beilage 5] Standard R016 Beilage 5: SOA-Glossar 11/11