Herausforderung in SAP API Management

SAP API Management ist eine leistungsfähige Plattform, um Schnittstellen zu verwalten, abzusichern und zu überwachen. Allerdings erfordert das Erstellen von API-Spezifikationen ein tiefes Verständnis von OpenAPI (OAS) und den entsprechenden YAML-Strukturen. Fehler beim Einrücken, vergessene Doppelpunkte oder falsche Formatierungen sind schnell passiert und kosten Zeit.

‍

Stoplight Studio als Lösung

Stoplight Studio ist ein modernes Tool, das auf API-Design-First setzt. Statt YAML-Code von Hand zu schreiben, können Entwickler und Architekten APIs in einer benutzerfreundlichen Oberfläche modellieren. Das Tool erzeugt automatisch eine valide OpenAPI-Spezifikation in YAML oder JSON, die anschließend direkt in SAP API Management importiert werden kann.

Vorteile von Stoplight Studio:

• Visuelles API-Design: Endpunkte, Methoden und Parameter lassen sich per Klick hinzufügen.

• Automatische YAML/JSON-Generierung: Hinter den Kulissen wird stets eine saubere OpenAPI-Datei gepflegt.

• ermöglicht, direkt aus einer Beispielnachricht automatisch ein passendes Schema zu erstellen. Das spart viel Zeit, besonders dann, wenn die Payload sehr umfangreich oder komplex ist.

• Versionierung & Zusammenarbeit: Über Git®-Anbindung lassen sich Spezifikationen versionieren und im Team entwickeln.

‍

Workflow: Von Stoplight zu SAP API Management

1. API in Stoplight Studio modellieren – Endpunkte, Schemas und Security-Settings definieren.

2. OpenAPI-Datei exportieren – Export als YAML-Datei (OpenAPI 2.0 oder 3.0).

  Beispiel-Export einer kleinen Demo-API:

‍

‍

3. Import in SAP API Management. Den Code aus der YAML-Datei einfach per Copy-Paste in den API Designer einfügen.

‍

‍

Kritik am SAP API Management

So hilfreich SAP API Management im Alltag ist, gibt es einige Punkte, die den Workflow erschweren:

• Spezifikation hat keinen direkten Einfluss auf den API Proxy - Obwohl man eine OpenAPI-Spezifikation hochlädt, wird diese nicht automatisch mit dem Proxy verknüpft.

• Fehlende Validierung gegen die Spezifikation – Angaben wie Pflicht-Header, Query-Parameter oder Schema-Definitionen werden nicht automatisch überprüft. Entwickler müssen selbst Policies schreiben, um solche Regeln zu erzwingen und dies ist mit viel Aufwand verbunden.

• Payload-Validierung nur eingeschränkt möglich – Eine Validierung der Payload ist im SAP API Management zwar möglich, aber ausschließlich für XML-Daten. In einer Zeit, in der JSON längst Standard ist, wirkt das nicht zeitgemäß. (Siehe dazu auch den Blog JSON vs. XML.) Theoretisch könnte man eine JSON-Payload in den Policies erst nach XML konvertieren und dann validieren, denn eine Funktion für die Konvertierung wird Standardmäßig bereit gestellt. doch das bedeutet zusätzlichen Implementierungsaufwand und führt zu unnötiger Komplexität.

• Aufwendige XML-Validierung – Selbst wenn man XML validiert, benötigt man dafür ein eigenes WSDL-Schema, das innerhalb der Policies gepflegt werden muss. Auf die im Proxy definierte Spezifikation lässt sich dabei nicht zurückgreifen.

• Nur rudimentäre Prüfungen sind einfach machbar – Was relativ leicht geht, ist die Validierung von HTTP-Methoden (GET, POST, DELETE). Doch für komplexere Validierungen stößt man schnell an Grenzen.

Fazit: Die OpenAPI-Spezifikation im API Management dient derzeit ausschließlich der Dokumentation und hat keinen direkten Einfluss auf die Funktionsweise des Proxies. Dennoch empfehle ich, die Spezifikation so sorgfältig wie möglich zu pflegen. Durch die Exportfunktion lässt sie sich die Spezifikation nicht nur den API-Nutzern zur Verfügung stellen, sondern kann beispielsweise auch in der Cloud Integration für grafische Mappings genutzt werden. Zudem bietet sie Entwicklern eine schnelle und übersichtliche Darstellung des API-Proxies.

Meine Empfehlung zur Validierung:
Verzichtet besser darauf, Validierungen direkt in den Proxy-Policies umzusetzen. Die Komplexität ist hier einfach zu hoch, und niemand möchte der Kollege sein, der später an diesem Proxy verzweifelt 😅.
Praktischer ist es, die Daten zunächst an die Cloud Integration zu schicken und dort die Validierung vorzunehmen. Das macht die Wartung wesentlich übersichtlicher und einfacher. Zwar habt ihr damit eine zusätzliche Komponente im Prozess, aber aus meiner Sicht lohnt sich dieser kleine Schritt definitiv.

‍

Best Practices

• Namenskonventionen einhalten – Bereits in Stoplight sollte man eine konsistente Struktur aufbauen.

• Reusable Components nutzen – Schemas und Parameter können zentral definiert und mehrfach verwendet werden.

• Iterativ vorgehen – API zuerst entwerfen, im Team reviewen, dann nach SAP importieren.

‍

Fazit

Mit Stoplight Studio lassen sich API-Spezifikationen für SAP API Management deutlich einfacher und effizienter erstellen. Anstatt sich mit komplexem YAML-Code abzumühen, können Teams visuell modellieren und validierte Spezifikationen generieren. Das spart Zeit, reduziert Fehlerquellen und fördert die Zusammenarbeit.

Trotz einiger Einschränkungen im SAP API Management, insbesondere der fehlenden Validierung gegen die OpenAPI-Spezifikation, bringt die Kombination mit Stoplight einen klaren Vorteil: saubere, dokumentierte APIs, die als Grundlage für Policies und Governance dienen können.

‍

Du stehst vor einer ähnlichen Herausforderung? Lass uns gemeinsam einen Blick auf deine Systemlandschaft werfen. Wir analysieren deine Anforderungen und bauen dir eine maßgeschneiderte Integrationsarchitektur.