OGC API

Jede API stellt eine OGC Web API bereit, d.h., eine API, die Konformitätsklassen aus OGC-API-Standards implementiert.

Grundsätzliche Regeln

Auswahl des Antwortformats

Bei Operationen, die eine Antwort zurückliefern, wird das Format nach den Standard-HTTP-Regeln standardmäßig über Content-Negotiation und den Accept-Header ermittelt.

Alle GET-Operationen mit mehr als einem Ausgabeformat unterstützen zusätzlich den Query-Parameter f. Über diesen Parameter kann das Ausgabeformat der Antwort auch direkt ausgewählt werden. Wenn kein Wert angegeben wird, gelten die Standard-HTTP-Regeln, d.h. der Accept-Header wird zur Bestimmung des Formats verwendet. Die unterstützten Formate hängen von der Ressource und von der API-Konfiguration ab.

Auswahl der Antwortsprache

Bei Operationen, die eine Antwort zurückliefern, wird die verwendete Sprache bei linguistischen Texten nach den Standard-HTTP-Regeln standardmäßig über Content-Negotiation und den Accept-Language-Header ermittelt.

Sofern die entsprechende Option im Baustein "Common Core" aktiviert ist, unterstützen alle GET-Operationen zusätzlich den Query-Parameter lang. Über diesen Parameter kann die Sprache auch direkt ausgewählt werden. Wenn kein Wert angegeben wird, gelten die Standard-HTTP-Regeln, wie oben beschrieben. Die erlaubten Werte hängen von der Ressource und von der API-Konfiguration ab. Die Unterstüzung für Mehrsprachigkeit ist derzeit begrenzt. Es gibt vier Arten von Quellen für Texte:

• Texte zu festen Elementen der API: Diese werden von ldproxy erzeugt, z.B. die Texte der Titel von Links oder feste Textbausteine in der HTML-Ausgabe. Derzeit werden die Sprachen "Deutsch" (de) und "Englisch" (en) unterstützt.
• Texte aus Attributen in den Daten: Hier gibt es noch keine Unterstützung, wie die Rückgabe bei mehrsprachigen Daten in Abhängigkeit von der Ausgabesprache gesteuert werden kann.
• Texte aus der API-Konfiguration, insbesondere zum Datenschema: Hier gibt es noch keine Unterstützung, wie die Rückgabe bei mehrsprachigen Daten in Abhängigkeit von der Ausgabesprache gesteuert werden kann.
• Fehlermeldungen der API: Diese sind immer in Englisch, die Meldungen sind aktuell Bestandteil des Codes.

Pfadangaben

Alle Pfadangaben in dieser Dokumentation sind relativ zur Basis-URI der API. Ist dies zum Beispiel https://example.com/pfad/zu/apis/{apiId} und lautet der relative Pfad einer Ressource collections dann ist die URI der Ressource https://example.com/pfad/zu/apis/{apiId}/collections.

Konfiguration

Informationen zu den einzelnen API-Bausteinen finden Sie hier, siehe api in der nachfolgenden Tabelle.

Name	Default	Beschreibung	Typ	Seit
id		Eindeutiger Identifikator des Entities, muss dem Dateinamen entsprechen. Erlaubt sind Buchstaben (A-Z, a-z), Ziffern (0-9), der Unterstrich ("_") und der Bindestrich ("-").	string	v2.0
label	{id}	Menschenlesbare Bezeichnung.	string	v2.0
description	""	Menschenlesbare Beschreibung.	string	v2.0
enabled	true	Option um die Entity zu deaktivieren, was bedeutet, dass sie für andere Entities nicht verfügbar ist und Hintergrundprozesse nicht laufen.	boolean	v2.0
apiVersion	null	Fügt dem URL-Pfad eine Version hinzu , anstatt von /{id} ist dieser dann /{id}/v{apiVersion}.	number	v2.0
auto	false	Steuert ob fehlende Definitionen beim Start automatisch aus der Datenquelle bestimmt werden sollen (Auto-Modus).	boolean	v2.0
serviceType	OGC_API	Immer OGC_API.	string	v2.0
metadata	{}	Allgemeine Metadaten für die API.	object	v2.0
externalDocs	{}	Verweis auf ein Dokument oder eine Website mit weiteren Informationen über diese API.	object	v2.1
defaultExtent	{ "spatialComputed": true, "temporalComputed": true }	Die räumliche und zeitliche Ausdehnung der Daten wird normalerweise aus den Daten während des Starts der API abgeleitet, aber die Angaben können auch in der Konfiguration gesetzt werden.	object	v2.0
defaultCaching	{}	Setzt feste Werte für HTTP-Caching-Header für die Ressourcen.	object	v3.1
accessControl	{}	Access Control konfigurieren.	object	v3.3
apiValidation	NONE	Beim Start einer API kann die Konfiguration validiert werden. Die unterstützten Werte sind NONE, LAX und STRICT. Bei STRICT wird der Start einer API mit Warnungen blockiert, während eine API mit Warnungen, aber ohne Fehler mit LAX startet. Wenn der Wert auf NONE gesetzt wird, findet keine Überprüfung statt. Warnungen werden für Probleme in der Konfiguration ausgegeben, die die Verwendung der API beeinträchtigen können, während Fehler für Fälle ausgegeben werden, in denen die API nicht verwendet werden kann. Normalerweise wird die API-Validierung während des Starts nur in Entwicklungs- und Testumgebungen verwendet, da die API-Validierung zu einer langsameren Startzeit führt und in Produktionsumgebungen nicht notwendig sein sollte.	string	v2.1
tags	[]	Ordnet der API die aufgelisteten Tags zu. Die Tags müssen jeweils Strings ohne Leerzeichen sein. Die Tags werden im API-Katalog angezeigt und können über den Query-Parameter tags zur Filterung der in der API-Katalog-Antwort zurückgelieferten APIs verwendet werden, z.B. tags=INSPIRE.	array	v2.1
api	[]	API-Bausteine der API konfigurieren.	array	v2.0
collections	{}	Ein Objekt mit der spezifischen Konfiguration zu jeder Objektart, der Name der Objektart ist der Schlüssel, der Wert ein Collection-Objekt.	object	v2.0

Collection

Jedes Collection-Objekt beschreibt eine Objektart aus einem Feature Provider (derzeit werden nur Feature Collections von ldproxy unterstützt). Es setzt sich aus den folgenden Eigenschaften zusammen:

Name	Default	Beschreibung	Typ	Seit
id		Eindeutiger Identifikator, erlaubt sind Buchstaben (A-Z, a-z), Ziffern (0-9), der Unterstrich ("_") und der Bindestrich ("-").	string	v2.0
label	{id}	Menschenlesbare Bezeichnung.	string	v2.0
description	""	Menschenlesbare Beschreibung.	string	v2.0
enabled	true	Die Collection aktivieren?	boolean	v2.0
persistentUriTemplate	null	Über die Feature-Ressource hat jedes Feature zwar eine feste URI, die für Links verwendet werden kann, allerdings ist die URI nur so lange stabil, wie die API stabil bleibt. Um von Veränderungen in der URI unabhängig zu sein, kann es sinnvoll oder gewünscht sein, API-unabhängige URIs für die Features zu definieren und von diesen URIs auf die jeweils gültige API-URI weiterzuleiten. Diese kanonische URI kann auch in ldproxy konfiguriert und bei den Features kodiert werden. Hierfür ist ein Muster der Feature-URI anzugeben, wobei {{value}} als Ersetzungspunkt für den lokalen Identifikator des Features in der API angegeben werden kann.	string	v2.0
additionalLinks	[]	Erlaubt es, zusätzliche Links bei jeder Objektart zu ergänzen. Der Wert ist ein Array von Link-Objekten. Anzugeben sind jeweils mindestens die URI (href), der anzuzeigende Text (label) und die Link-Relation (rel).	array	v2.0
api	[]	Bausteine konfigurieren.	array	v2.0

Bausteine

Ein Array dieser Baustein-Konfigurationen steht auf der Ebene der gesamten API und für jede Collection zur Verfügung. Die jeweils gültige Konfiguration ergibt sich aus der Priorisierung:

• Ist nichts angegeben, dann gelten die im ldproxy-Code vordefinierten Standardwerte. Diese sind bei den jeweiligen Bausteinen spezifiziert.
• Diese systemseitigen Standardwerte können von den Angaben im Verzeichnis defaults überschrieben werden.
• Diese deploymentweiten Standardwerte können von den Angaben in der API-Definition auf Ebene der API überschrieben werden.
• Diese API-weiten Standardwerte können bei den Collection-Ressourcen und untergeordneten Ressourcen von den Angaben in der API-Definition auf Ebene der Collection überschrieben werden.
• Diese Werte können durch Angaben im Verzeichnis overrides überschrieben werden.

Metadaten

Über dieses Objekt können grundlegende Metadaten zur API (Version, Kontaktdaten, Lizenzinformationen) festgelegt werden. Erlaubt sind die folgenden Elemente mit den Ressourcen, in denen die Angabe verwendet wird:

• version: API-Definition
• contactName: API-Definition, HTML-Landing-Page
• contactUrl: API-Definition, HTML-Landing-Page
• contactEmail: API-Definition, HTML-Landing-Page
• contactPhone: HTML-Landing-Page
• licenseName: API-Definition, HTML-Landing-Page, Feature-Collections, Feature-Collection
• licenseUrl: API-Definition, HTML-Landing-Page, Feature-Collections, Feature-Collection
• keywords: Meta-Tags und schema:Dataset in HTML-Landing-Page
• attribution: Landing-Page, Karten
• creatorName: schema:Dataset in HTML
• creatorUrl: schema:Dataset in HTML
• creatorLogoUrl: schema:Dataset in HTML
• publisherName: schema:Dataset in HTML
• publisherUrl: schema:Dataset in HTML
• publisherLogoUrl: schema:Dataset in HTML

Alle Angaben sind Strings, bis auf keywords, die als Array von Strings angegeben werden.

Name	Default	Beschreibung	Typ	Seit
contactName		Optionaler Name einer Kontaktperson oder -organisation für die API.	string	v2.0
contactUrl		Optionale URL einer Kontakt-Webseite für die API.	string	v2.0
contactEmail		Optionale Emailadresse für Informationen über die API.	string	v2.0
contactPhone		Optionale Telefonnummer für Informationen über die API.	string	v2.0
creatorName		Optionaler Name des Erzeugers der Daten aus dieser API.	string	v3.0
creatorUrl		Optionale URL der Website des Erzeugers der Daten aus dieser API.	string	v3.0
creatorLogoUrl		Optionale URL einer Logo-Bilddatei des Erzeugers der Daten aus dieser API.	string	v3.0
publisherName		Optionaler Name des Herausgebers dieser API.	string	v3.0
publisherUrl		Optionale URL der Website des Herausgebers dieser API.	string	v3.0
publisherLogoUrl		Optionale URL einer Logo-Bilddatei des Herausgebers dieser API.	string	v3.0
licenseName		Name der Lizenz der Daten aus dieser API.	string	v2.0
licenseUrl		URL der Lizenz der Daten aus dieser API.	string	v2.0
keywords		Schlagworte die diese API beschreiben.	array	v2.0
version	1.0.0	Version der API in der OpenAPI-Definition.	string	v2.0
attribution		Text für die Namensnennung, wenn Daten aus dieser API verwendet werden, z.B. in einer Karte.	string	v3.0

Externes Dokument

Es kann ein externes Dokument mit weiteren Informationen angegeben werden, auf das aus der API verlinkt wird. Anzugeben ist die url des Dokuments, die Angabe von description wird empfohlen.

Name	Default	Beschreibung	Typ	Seit
description		Beschreibung des Inhalts des Dokuments oder der Website.	string	v2.1
url		URL des Dokuments oder der Website.	string	v2.1

Ausdehnung der Daten

Es kann ein Standardwert für die räumliche (spatial) und/oder zeitliche (temporal) Ausdehnung der Daten angeben werden, die bei den Objektarten verwendet wird, wenn dort keine anderslautende Ausdehnung spezifiziert wird und die automatische Ableitung deaktiviert ist.

Für die räumliche Ausdehnung sind die folgenden Eigenschaften anzugeben (alle Angaben im Koordinatenreferenzsystem WGS 84): xmin (westlicher Längengrad), ymin (südlicher Breitengrad), xmax (östlicher Längengrad), ymax (nördlicher Breitengrad).

Für die zeitliche Ausdehnung sind die folgenden Eigenschaften anzugeben (alle Angaben in Millisekunden seit dem 1.1.1970): start, end.

Es handelt sich hierbei nicht um die Ausdehnung des Datensatzes insgesamt, dieser wird stets automatisch aus den Ausdehnungen der einzelnen Objektarten ermittelt.

Soll die räumliche Ausdehnung nicht automatisch aus den Daten der Objektarten beim Start von ldproxy ermittelt werden, kann spatialComputed mit dem Wert false angegeben werden.

Soll die zeitliche Ausdehnung nicht automatisch aus den Daten einer Objektart beim Start von ldproxy ermittelt werden, kann temporalComputed mit dem Wert false angegeben werden.

Bei großen Datenmengen verzögert die automatische Bestimmung die Zeitdauer, bis die API verfügbar ist.

Name	Default	Beschreibung	Typ	Seit
spatial		Längengrad am westlichen und östlichen Ende (xmin, xmax), Breite am südlichen und nördlichen Ende (ymin, ymax) der Daten. Optional können auch die minimale und maximale Höhe (zmin, zmax) angegeben werden.	object	v2.0
spatialComputed	true	Die räumliche Ausdehnung jeder Collection wird beim Starten der API automatisch aus den Daten abgeleitet. Wenn die Collection keine räumlichen Eigenschaften hat, hat die Collection keine räumliche Ausdehnung.	boolean	v2.0
temporal		Beginn (start) und Ende (end) der zeitlichen Ausdehnung der Daten. Die Angabe erfolgt als Textstring gemäß RFC 3339 in UTC. Fehlende Angaben stehen für ein unbegrenztes Intervall.	object	v2.0
temporalComputed	true	Die zeitliche Ausdehnung jeder Collection wird beim Starten der API automatisch aus den Daten abgeleitet. Wenn die Collection keine zeitlichen Eigenschaften hat, hat die Collection keine zeitliche Ausdehnung.	boolean	v2.0

Caching

Die folgenden HTTP-Header für HTTP-Caching werden in Antworten gesetzt - soweit diese für die jeweilige Ressource bestimmt werden können:

• Last-Modified: Der Zeitstempel der letzten Änderung wird - sofern möglich - aus der
  zurückzugebenden Repräsentation der Ressource bestimmt, z.B. aus dem Änderungsdatum einer
  Datei. Er kann über eine Konfigurationseinstellung überschrieben werden (siehe unten).
• ETag: Der Tag wird - sofern möglich - aus der zurückzugebenden Repräsentation der Ressource
  bestimmt.
• Cache-Control: Der Header wird nur gesetzt, wenn er für die Ressourcen des
  Bausteins konfiguriert wurde (siehe unten).
• Expires: Der Header wird nur gesetzt, wenn er
  für die Ressourcen des Bausteins konfiguriert wurde (siehe unten).

In jedem Baustein, das Ressourcen bereitstellt und nicht nur Query-Parameter oder Ausgabeformate realisiert, ist eine Konfigurationsoption caching, deren Wert ein Objekt mit den folgenden, optionalen Einträgen ist.

Name	Default	Beschreibung	Typ	Seit
lastModified	null	Für die Ressourcen in dem Baustein wird der Last-Modified Header auf den konfigurierten Wert gesetzt. Der Wert überschreibt einen ggf. aus der Ressource bestimmten Änderungszeitpunkt.	string	v3.1
expires	null	Für die Ressourcen in dem Baustein wird der Expires Header auf den konfigurierten Wert gesetzt.	string	v3.1
cacheControl	null	Für die Ressourcen in dem Baustein wird der Cache-Control Header auf den konfigurierten Wert gesetzt. Ausnahme sind die Features und Feature Ressourcen, bei denen cacheControlItems zu verwenden ist.	string	v3.1
cacheControlItems	null	Für die Features und Feature Ressourcen wird der Cache-Control Header auf den konfigurierten Wert gesetzt.	string	v3.1

Access Control

Absicherung für alle API Operationen (Kombination aus Endpunkt und HTTP-Methode).

Berechtigungen

Die Absicherung basiert auf Berechtigungen und Berechtigungsgruppen.

Berechtigungen sind eine Kombination aus Gruppen-Präfix (siehe unten) und einer OpenAPI Operation-Id (ohne jeglichen Präfix), z.B. data:getItems oder tiles:getTile. Diese können verwendet werden, wenn eine fein-granularere Absicherung benötigt wird, als sie mit Berechtigungsgruppen möglich ist.

Berechtigungsgruppen

Das sind die vordefinierten Main-Berechtigungsgruppen, jede Operation/Berechtigung ist in genau einer Main-Gruppe enthalten:

• discover: Lesen von API Landing Pages, Conformance Declarations und OpenAPI Definitionen
• collections:read: Lesen von Metadaten zu Feature Collections
• data:read: Lesen und Abfragen von Features
• data:write: Ändern von Features
• tiles:read: Lesen von Tiles
• styles:read: Lesen von Styles und deren Metadaten
• styles:write: Ändern von Styles und deren Metadaten
• resources:read: Lesen von Dateiressourcen
• resources:write: Ändern von Dateiressourcen
• search:read: Lesen von Stored Queries und deren Parameter
• search:write: Ändern von Stored Queries
• routes:read: Lesen von gespeicherten Routen und deren Definition
• routes:write: Berechnen und Speichern von Routen, Löschen gespeicherter Routen

Das sind die vordefinierten Parent-Berechtigungsgruppen (komfortable Vereinigungen von Main-Gruppen):

• collections: enthält collections:read
• data: enthält data:read und data:write
• tiles: enthält tiles:read
• styles: enthält styles:read und styles:write
• resources: enthält resources:read und resources:write
• search: enthält search:read und search:write
• routes: enthält routes:read und routes:write

Das sind die vordefinierten Base-Berechtigungsgruppen (komfortable Vereinigungen von Main-Gruppen):

• read: enthält discover, collections:read, data:read, tiles:read, styles:read, resources:read, search:read und routes:read
• write: enthält data:write, styles:write, resources:write, search:write und routes:write

Benutzerdefinierte Berechtigungsgruppen werden in groups definiert, sie können Berechtigungen und/oder vordefinierte Berechtigungsgruppen enthalten.

Die spezielle Berechtigungsgruppe public definiert die Liste der Berechtigungen und/oder vordefinierten Berechtigungsgruppen, die jeder Benutzer besitzt, ob angemeldet oder nicht.

Daten-spezifische Berechtigungen

Die oben beschriebenen Berechtigungen gewähren Zugriff zu jeder API und Collection. Um den Zugriff auf bestimmte APIs oder Collections einzuschränken, kann ein Suffix zu Berechtigungsgruppen und Berechtigungen hinzugefügt werden, z.B. read::daraa oder data:getItems::daraa:AeronauticSrf.

Scopes

OAuth2 Scopes sind ein optionaler zusätzlicher Autorisierungs-Layer. Sie werden typischerweise verwendet wenn einer Fremd-Applikation im Namen eines Users Zugriff auf eine API gewährt werden soll. Scopes erlauben es dann zu beschränken welche der Berechtigungen des Users der Applikation gewährt werden sollen. Die Applikation würde die benötigten Scopes anfragen und dem User würde ein Einwilligungs-Formular präsentiert in dem er die Scopes auswählen kann, die er gewähren will.

Scopes sind standardmäßig deaktiviert und können durch Setzen der scopes Option aktiviert werden. Der Wert ist eine Liste von Berechtigungsgruppen-Typen die als Scopes verwendet werden sollen. Das erlaubt die Granularität der Scopes festzulegen, da zu viele Scopes in einem Einwilligungs-Formular überwältigen können und alle aktivierten Scopes auch im Identity-Provider existieren müssen.

Zum Beispiel würde das Setzen von scopes auf [BASIC] die Scopes read und write aktivieren. Wenn ein User einer Applikation dann den Scope write gewähren würde, heißt das nicht automatisch, dass die Applikation irgendetwas schreiben darf. Was die Applikation schreiben darf wird immer noch durch die Berechtigungen des Users beschränkt. Aber den Scope write nicht zu gewähren ist ein einfacher Weg jeglichen Schreibzugriff zu verbieten, auch wenn der User entsprechende Rechte hat.

Authentifizierung and Autorisierung

Um authentifizierte Benutzer zu unterstützen, muss ein Bearer-Token im Authorization-Header in Anfragen an die API inkludiert werden. Die Validierung und Auswertung dieser Tokens muss in der globalen Konfiguration konfiguriert werden.

Um zu bestimmen ob ein Benutzer autorisiert ist die angefragte Operation auszuführen, werden die folgenden Schritte durchgeführt:

1. Wenn die Operation von der public-Gruppe abgedeckt ist, wird die Autorisierung gewährt, auch wenn kein Token oder ein invalides
   Token bereitgestellt wurden. (Dann Sprung zu 6.)
2. Wenn kein Token oder ein invalides Token (falsche Signatur oder abgelaufen) bereitgestellt wurden, wird die Autorisierung verweigert.
3. Wenn audience nicht leer ist und sich nicht mit dem Audience-Claim des gegebenen Tokens überschneidet, wird die Autorisierung verweigert.
4. Wenn scopes nicht leer ist und der Scope-Claim des gegebenen Tokens nicht mindestens eine Berechtigungsgruppe enthält, die die Operation
   abdeckt, wird die Autorisierung verweigert.
5. Wenn der Permissions-Claim des gegebenen Tokens nicht mindestens eine Berechtigung, vordefinierte
   Berechtigungsgruppe oder benutzerdefinierte Berechtigungsgruppe enthält, die die Operation
   abdeckt, wird die Autorisierung verweigert.
6. Wenn policies aktiviert ist und der PDP Deny zurück gibt, wird die Autorisierung verweigert.

Konfiguration

Name	Default	Beschreibung	Typ	Seit
enabled	true	Option, um die Absicherung zu deaktivieren.	boolean	v3.3
groups	{public: [read]}	Definition von benutzerdefinierten Berechtigungsgruppen, der Key ist der Name der Gruppe, der Werte eine Liste von Berechtigungen und/oder vordefinierten Berechtigungsgruppen. Die Gruppe public definiert die Liste der Berechtigungen, die jeder Benutzer besitzt, ob angemeldet oder nicht.	object	v3.5
scopes	[]	Wenn nicht leer, werden OAuth2 Scopes zur OpenAPI Definition hinzugefügt. Dann werden nur Tokens akzeptiert, die mindestens einen Scope enthalten, der die angeforderte Operation abdeckt. Scopes verwenden Berechtigungsgruppen, Werte sind die Arten von Berechtigungsgruppen, die verwendet werden sollen: BASE (z.B. read), PARENT (z.B. data), MAIN (z.B. data:read) und CUSTOM (alles in groups definierte außer public) sein.	array	v3.5
audience	[]	Wenn nicht leer, werden nur Tokens akzeptiert, die mindestens einen der gegebenen Werte im Audience-Claim enthalten.	array	v3.5
policies	null	Optionaler zusätzlicher Autorisierungs-Layer mittels eines Policy Decision Point, der in der globalen Konfiguration definiert wird, siehe Policies.	object	v3.5

Policies

Name	Default	Beschreibung	Typ	Seit
enabled	false	Aktiviert einen zusätzlichen Autorisierungs-Layer mittels eines Policy Decision Point, der in der globalen Konfiguration definiert wird.	boolean	v3.5
attributes	{}	Fügt die gegebenen Attribute dem Request an den Policy Decision Point hinzu. Keys sind Attribut-Ids, Werte sind Objekte mit einem einzelnen Key, entweder constant für feste Strings, property für Property-Pfade oder parameter für Query-Parameter. Attribute mit property sind nur für Operationen relevant die Features involvieren. Kann pro Collection definiert werden.	object	v3.5
obligations	{}	Wendet die angegebenen Attribute aus Obligations an, die der Policy Decision Point zurückgibt. Keys sind Attribut-Ids, Werte sind Objekte mit einem einzelnen Key parameter für Query-Parameter. Parameter die in einer Obligation definiert sind überschreiben Parameter im Request, mit der Ausnahme von filter, das mit AND zusammengeführt wird. Kann pro Collection definiert werden.	object	v3.5

Beispiele

Als Beispiel siehe die API-Konfiguration der API Weinlagen in Rheinland-Pfalz.

Speicherung

API-Konfigurationen liegen im Store als Entities mit Typ services.