Seminar NeoNephos: Open Resource Discovery – Dienste und APIs beschreiben

Seminarbeschreibung

Eine einheitliche Dienstlandschaft benötigt auffindbare und verständliche Metadaten. Das Seminar zeigt, wie Anwendungen mit Open Resource Discovery ihre eigenen Ressourcen und Fähigkeiten beschreiben. Vorhandene API-Definitionen werden dabei eingebunden und durch fachliche, technische und organisatorische Metadaten ergänzt.

Eine Beispielanwendung dient als roter Faden für Modellierung, Bereitstellung und Auswertung. Der Kurs untersucht zugleich die Grenzen des Ansatzes: ORD beschreibt Ressourcen und unterstützt deren Auffinden; tatsächliche Provisionierung, Authentifizierung am Fachdienst und dessen laufende Nutzung bleiben eigenständige Aufgaben. Das erleichtert eine saubere Integration in Portale und Kataloge.

Inhaltsübersicht

• Protokoll und Rollen
• Metadaten modellieren
• Dokumente und Einstiegspunkt
• Validierung und Qualität
• Kataloge und Sichtbarkeit
• Versionierung und Betrieb

Protokoll und Rollen

• Anwendung als Metadatenanbieter und auswertenden Verbraucher mit ihren jeweiligen Aufgaben unterscheiden.
• Selbstbeschreibung, Veröffentlichung und Discovery in die bestehende API- und Integrationslandschaft einordnen.
• Die selbst beschriebenen Ressourcen auf den Verantwortungsbereich der jeweiligen Anwendung begrenzen.

Metadaten modellieren

• Ressourcen mit stabilen Identitäten, Versionen, Beschreibungen und passenden Beziehungen modellieren.
• Vorhandene API- und Ereignisbeschreibungen zuordnen und fachliche Begriffe einheitlich verwenden.
• Technische Identitäten und verständliche Anzeigenamen getrennt behandeln, damit Umbenennungen keine Beziehungen beschädigen.

Dokumente und Einstiegspunkt

• Die benötigte ORD-Konfiguration und ein passendes ORD-Dokument für die Beispielanwendung aufbauen.
• Auffindbarkeit, Abruf und Verweisauflösung in der Testumgebung mit HTTP-Werkzeugen prüfen.
• Den tatsächlich veröffentlichten Inhalt über den Verbraucherzugriff und nicht nur im lokalen Editor kontrollieren.

Validierung und Qualität

• Dokumente gegen das passende Schema validieren und strukturelle von fachlichen Fehlern unterscheiden.
• Unvollständige Metadaten, nicht eindeutige Identitäten und ungültige Beziehungen anhand gezielter Testfälle korrigieren.
• Zusätzlich zur Schema-Konformität prüfen, ob die Beschreibungen für einen fremden Integrationsentwickler verständlich sind.

Kataloge und Sichtbarkeit

• Einen einfachen Verbraucher Metadaten abrufen und zu einer kleinen Übersicht zusammenführen lassen.
• Öffentliche, interne und mandantenabhängige Informationen bewusst trennen und die Sichtbarkeit mit Testkonten prüfen.
• Metadatenzugriff und Berechtigung zur späteren Nutzung des beschriebenen Dienstes getrennt bewerten.

Versionierung und Betrieb

• Änderungen der Metadaten und der beschriebenen APIs mit nachvollziehbaren Versionsregeln verbinden.
• Abruffehler, veraltete Einträge und unvollständige Aktualisierungen über wiederholbare Prüfungen erkennen.
• Eine geänderte Ressourcenbeziehung nachvollziehen und die Aktualisierung abhängiger Übersichten gezielt kontrollieren.

Praxisübungen

1. Eine Beispiel-API inventarisieren und ihre Ressourcen mit eindeutigen Identitäten und verständlichen Beschreibungen modellieren.
2. ORD-Konfiguration und Dokumente im Testdienst bereitstellen und den Abruf vom Einstiegspunkt aus nachvollziehen.
3. Die Dokumente validieren, absichtliche Fehler berichtigen und die aufgelösten Beziehungen erneut kontrollieren.
4. Eine Metadatenänderung veröffentlichen und in einem einfachen Testkatalog ihre Sichtbarkeit sowie Aktualisierung prüfen.

Schulungsumgebung

Der Kunde stellt eine lokale oder isolierte Web-Testumgebung, einen Editor, ein Git-Repository und die passenden Schema- und Validierungswerkzeuge. Es werden ausschließlich fiktive oder anonymisierte Dienstbeschreibungen eingesetzt.