API‐Gestaltung

Open API:

OpenAPI gibt eine einheitliche Struktur und Dokumentationsweise vor, die wir auch für unsere API verwenden können. Im Grunde basiert alles darauf, ein OpenAPI-Dokument zu verfassen und zu pflegen, welches die API beschreibt und als Dokumentation gilt:

• Datenformat dieser Datei ist JSON
• Das OpenAPI-Object gibt Metadaten zur API (z. B. zu allen vorhandenen Pfaden und wie sie funktionieren)
• Es gibt Spezifikationen zu Request-&Response-Bodies und vielem mehr
• Minimalbspl:

  {
      "openapi": "3.1.0",
      "info": {
          "title": "Minimalbspl",
          "version": "1.0.0"
      }
  }

• Man kann auch benötigte API_Keys etc im "Security Requirement Object" angeben
• Am besten im Anwendungsfall in Quelle schauen

Quelle: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md & https://swagger.io/specification/

OGC-API:

Die OGC-Web-API-Spezifikation richtet sich glaube ich in erster Linie an die Bereitstellung von Geodaten. Wir werden jedoch an sich keine Datensammlung verwalten und zugreifbar machen, sondern quasi nur 3 Endpoints (Training+Ergebnis, Demo, Model) + Doku-Endpoints anbieten. Daher ist sie nicht 100% relevant für uns, beschreibt aber einige nützliche Best-Practices:

Prinzipien:

1. Vorhandene Funktionen nutzen statt neu implementiern
2. Einfache API (vorhersehbare Rückmeldung)
3. Bekannte Datenformate nutzen
4. Konsistente URIs (mit dokumentierter sinnvoller Struktur)
5. HTTP-Methoden (GET, POST, etc) nutzen/unterstützen
6. Suchkreterien hinter "?"
7. Error-Handling (Bspl:)

{ 
  "developer_message": "...",
  "user_message": "...",
  "error_code": "...",
  "contact_details": "..."  
}

8. inkl. passenden HTTP-Status-Codes (https://de.wikipedia.org/wiki/HTTP-Statuscode)
9. HTTP-Header nutzen
10. Für Operationen klare Verben nutzen
11. Metadaten unterstützen
12. Nutze API-Beschreibung (Mensch & Maschine)
13. Während Entwicklung schon testbar

Quelle: Matheus A., Terpstra F. and Masó J. (ed.) OGC Web API Guidelines (2021), available at https://github.com/opengeospatial/OGC-Web-API-Guidelines