WFS 3.0 Server (ogc api)

cardo bietet seit jeher verschiedene OGC Dienste an.

Der aktuelle Standard für WFS-Dienste ist die Version 3. Hier wird derzeit der Weg von XML-basierten Diensten hin zu REST-basierten Endpunkten beschritten, mit JSON als bevorzugtem Transportformat.

Die Dokumentation des Standards finden Sie hier (OGC API - Features - Part 1: Core)

In der cardo Version 4.1.1 haben wir eine erste Implementierung dieses Standards vorgenommen. Schwerpunkt soll zunächst die Datenbereitstellung als GeoJSON sein.

Die Implementierung ist noch nicht vollständig und kann sich noch ändern. Dies betrifft vor allem die proprietären Bestandteile. Wesentliche Änderungen an der API im Laufe der weiteren Entwicklung sind am Ende dieses Dokumentes vermerkt.

Generelle Hinweise

Alle Daten werden per Streaming geschrieben und es erfolgt kein Puffern der Daten. Der Speicherbedarf auf der Serverseite ist entsprechend gering und es ist daher seitens des Dienstes nicht nötig die Anzahl der abgegebenen Datensätze standardmäßig zu beschränken.

Am Rande: Wir sehen das vom Standard propagierte und auch sonst häufig anzutreffende erzwungene Chunking (d.h. Limit/Offset), vor allem für eine Server-Server-Kommunikation, ziemlich kritisch.

Der Datenabruf erfolgt intern ausschließlich über Iwan7. Die Ebenen werden bei Bedarf automatisch konvertiert.

Der Aufrufer muss für die Ebene das Export-Recht haben.

Der Parameter offset wird derzeit beim Datenabruf nicht unterstützt!

In der aktuellen GeoJSON-Spezifikation ist als Koordinatenbezugssystem (KBS, engl. CRS) für alle Geometrien 'CRS84' festgelegt. In einer ergänzenden Notiz wird jedoch erklärt, dass dies aus Gründen der Vermeidung von Problemen bei der Interoperabilität geschah. Besteht zwischen dem Abgebenden und dem Abrufenden Klarheit über das KBS der Daten steht der Verwendung anderer KBS nichts entgegen (RFC 7946, Abschnitt 4). Mit dem Parameter result-crs bieten wir daher die Möglichkeit an, die Koordinaten auch in einem anderen KBS ausgeben zu lassen.

Die Dienste sind in jeder Installation nach folgendem Schema abrufbar.

• Mit Anmeldung:

  https://IhrCardoServer/net4/ogcapi/collections/

• Ohne Anmeldung, d.h. als Benutzer "SYSTEM_ANONYMOUS_USER":

  https://IhrCardoServer/net4/public/ogcapi/collections/

---

Verfügbare Ebenen : "../ogcapi/collections/"

Entspricht 7.13. Feature collections.

Ruft eine Beschreibung aller verfügbaren Collections (Ebenen) ab.

Hierbei werden alle Ebenen abgerufen, für die der Aufrufer über die Berechtigung "Export" verfügt.

Bsp.: https://IhrCardoServer/net4/ogcapi/collections/

---

Beschreibung einer Ebene : "../ogcapi/collections/{collectionId}"

Entspricht 7.14. Feature collection.

Ruft die Beschreibung der mit collectionId bezeichneten Collection (Ebene) ab. Als collectionId wird der interne Ebenenname erwartet (L-Nummer).

Bsp.: https://IhrCardoServer/net4/ogcapi/collections/L120

Die Ausgabe wurde um das Element properties erweitert. Darin wird ein Array der Spaltendefinitionen der Ebene ausgegeben.

Der Typ für die Spaltenbeschreibung ist folgendermaßen definiert:

{
  name: string; //Spaltenname
  type: DataType; //Datentyp der Spalte
  flags?: FieldAttributeFlags; //besondere Attribute der Spalte
  length?: number; //max. Länge der Daten, falls für den Datentyp zutreffend
}

Eigenschaften, (als Flags kombinierbar):

public enum FieldAttributeFlags
{
  Default = 0,
  IsNotNull = 1,
  ComputedColumn = 2,
  RowId = 4,
  HasIndex = 8,
  UniqueValues = 16,
  HiddenSystemColumn = 32
}

Mögliche Datentypen sind:

public enum DataType
{
  Null,
  Boolean,
  SingleByte,
  Int16,
  UInt16,
  Int32,
  UInt32,
  Int64,
  UInt64,
  Double,
  DateTime,
  Text,
  Binary,
  Geom,
  Object
}

---

Daten einer Ebene : "../ogcapi/collections/{collectionId}/items"

Entspricht 7.15. Features.

Ruft die Daten der mit collectionId bezeichneten Collection (Ebene) ab. Als collectionId wird der interne Ebenenname erwartet (L-Nummer).

Wenn der Layer Dimension definiert, dann kann die Nummer der Schicht mit zwei aufeinanderfolgenden Punkten angegeben werden (Bsp.: L10..1).

Parameter

Alle Parameter sind optional.

standardisierte Parameter:

• limit=10 - Maximale Anzahl zurückzugebender Datensätze. Standardmäßig gibt es keine Beschränkung.

• offset - Der Parameter offset wird derzeit nicht unterstützt.

• bbox=x1,y1,x2,y2 - Box-Filter auf die Geometrien der Datensätze. Die Koordinaten werden entsprechend des KBS, wie im Parameter bbox-crs angegebenen bzw. dessen Standardwert interpretiert. Die Variante des bbox-Parameters mit 6 Teil-Werten (x1,y1,z1,x2,y2,z2) wird derzeit nicht unterstützt.

• bbox-crs=4326 - EPSG-Code des KBS in dem die Koordinaten der Bounding-Box interpretiert werden sollen. Ist der Parameter bbox-crs nicht angegeben, dann wird CRS84 (d.h. EPSG-Code 4326) angenommen.

propriertäre Parameter:

• result-crs=4326 - EPSG-Code des KBS in dem die Geometrien ausgegeben werden sollen. Standardmäßig erfolgt die Ausgabe im KBS 'CRS84' (EPSG-Code 4326).

• propertynames=a,b,c - Liste der Spaltennamen, die in der Ausgabe zurückgegeben werden sollen.

  Da die Geometrie auch nur eine "normale" Spalte ist, kann diese angegeben oder auch weggelassen werden. In dem Fall, dass die Geometrie fehlt, wird in GeoJSON ein Feature mit null-Geometrie ausgegeben.

• filter=xxx - Filter auf die Spalten der Datenquelle. Zur Zeit verwenden wir dafür unsere Expression-Syntax aus Iwan7.

  Bsp.:

  NENNER==17 AND zaehler==5

  In(nenner,1,2,3,4) or ST_Intersects(geom,'SRID=4326;POINT(12 51)')

  Beachten Sie, dass die Spaltennamen denen der Quelle entsprechen müssen. Die Spaltennamen sind in der Beschreibung der Collection ersichtlich. Weder Geometrie- noch ID-Spalten folgen einer besonderen Namenskonvention. Hintergrund ist, dass bspw. mehrere Geometriespalten vorhanden sein können bzw. die ID-Spalte nicht unbedingt "id" heißen muss. Filter-Geomeetrien sind als EWKT zu notieren.

  Die möglichen Operatoren und Funktionen sind unter Iwan7 Filter dokumentiert.

Sind bbox und filter angegeben, werden die Bedingungen aus beiden Parametern mit UND kombiniert.

• format=GeoJson - Ausgabeformat. Standardmäßig wird GeoJSON ausgegeben. Mögliche Werte sind (Groß-/Kleinschreibung beliebig):

  • GeoJson,
  • csv
  • csv/ewkt
  • csv/centroid

  Bei den CSV Formaten gilt:

  • Die erste Zeile enthält die Spaltennamen.
  • Als Trennzeichen der Spalten wird standardmäßig ein Komma verwendet. Ein abweichendes Trennzeichen kann mit dem Parameter delimiter angegeben werden.
  • Texte werden in doppelten Hochkomma ausgegeben. Evtl. vorhandene doppelte Hochkomma werden durch Verdoppelung maskiert.
  • Alle Fließkommazahlen werden immer in invarianter Kultur ausgegeben, d.h. Dezimaltrenner ist immer der Punkt.
  • Bool-Werte werden als true oder false ausgegeben.
  • DateTime-Werte werden immer im Format "yyyy-MM-dd" bzw "yyyy-MM-dd HH:mm:ss" (lokale Zeitzone des Servers) ausgegeben.
  • Geometrien werden ...
    • im Format csv nicht ausgegeben,
    • im Format csv/ewkt als EWKT-Text ausgegeben,
    • im Format csv/centroid als Schwerpunktkoordinate in zwei Spalten ausgegeben. Die Spaltennamen ergeben sich aus dem Spaltennamen der Geometrie, gefolgt von den Sufixen "_hor" und "_ver" (horizontal /vertikal), z.B. "geom_hor" und "geom_ver".

• delimiter=Comma - Trennzeichen der Spalten bei Ausgaben in den CSV-Formaten. Standardmäßig wird ein Komma verwendet. Mögliche Werte sind (Groß-/Kleinschreibung beliebig):

  • Comma
  • Semicolon
  • Tab
  • SingleSpace

Beispiele:

Achtung: Die Werte von URL-Parametern sind entsprechend RFC 3986 korrekt zu kodieren. Darauf wird in den folgenden Beispielen zugunsten der besseren Lesbarkeit verzichtet!

• Alle Datensätze, alle Spalten:

  https://IhrCardoServer/net4/ogcapi/collections/L120/items

• Alle Daten, die die Bedingung "nenner ist gleich 17 und zaehler ist gleich 1" erfüllen:

  https://IhrCardoServer/net4/ogcapi/collections/L120/items?filter=nenner==17 and zaehler==1

• Alle ID Werte, die die Bedingung "nenner ist gleich 17 und zaehler ist gleich 1" erfüllen:

  https://IhrCardoServer/net4/ogcapi/collections/L120/items?filter=nenner==17 and zaehler==1&propertyNames=ID

• Alle Geometrien, wo geom_flaeche kleiner 1000 ist http://IhrCardoServer/net4/ogcapi/collections/L159/items?filter=geom_flaeche<1000&propertyNames=geom

• Alle ALK-Nummern, wo der Stand nicht Grundbuchstand ist:

  http://IhrCardoServer/net4/ogcapi/collections/L159/items?filter=stand!="Grundbuchstand"&propertyNames=alknr

---

Einzelner Datensatz einer Ebene : "../ogcapi/collections/{collectionId}/items/{featureId}"

Ruft einen Datensatz, anhand des bei featureId genannten Primärschlüssewertes, aus der mit collectionId bezeichneten Collection (Ebene) ab.

Als collectionId wird der interne Ebenenname erwartet (L-Nummer). Als featureId wird der Primärschlüsselwert des Datensatzes erwartet.

Als Primärschlüsselspalte wird die Spalte verwendet, die intern mit dem Attribut RowId gekennzeichnet ist. Fehlt eine solche Spalte wird alternativ die erste Spalte verwendet, die mit dem Attribut UniqueValues markiert ist. Die Attribute der Spalten sind in der Beschreibung einer Collection ersichtlich.

Bsp.: https://IhrCardoServer/net4/ogcapi/collections/L120/18735

Ist kein Datensatz mit dem angegeben Primärschlüssel vorhanden, wir der Statuscode 404 generiert und ein leeres Objekt zurückgegeben.

Parameter

Alle Parameter sind optional.

propriertäre Parameter:

• result-crs=4326 - EPSG-Code des KBS in dem die Geometrien ausgegeben werden sollen. Standardmäßig erfolgt die Ausgabe im KBS 'CRS84' (EPSG-Code 4326).

---

Wesentliche Veränderungen der API

cardo 4.1.9

• Bei den Ausgaben des Dienstes wird keine Byte Order Mark (BOM) mehr mit rausgeschrieben. Speziell bei JSON-Ausgaben ist dies nicht zulässig und für sonstige Ausgaben im Charset UTF-8 ist die allgemeine Empfehlung, die BOM nicht rauszuschreiben.

cardo 4.1.3

• Die Geometrien werden nun entsprechend der Spezifikation im Standard im KBS 'CRS84' (EPSG 4326) ausgegeben, sofern kein anderes KBS mittels des Parameters result-crs vorgegeben wird.
• Der proprietäre Parameter crs wurde durch den standardisierten Parameter bbox-crs und proprietären Parameter result-crs abgelöst. Damit besteht nun auch die Möglichkeit unterschiedliche KBS für die Notation der BBox und die Ausgabe der Geometriedaten zu verwenden.
• Neuer Parameter format für den Datenabruf mit der Möglichkeit neben GeoJSON auch Daten im CSV-Format abzurufen, gepaart mit dem ebenfalls neuen Parameter delimiter
• Aufrufe der Endpunkte sind nun auch in Browsern via JavaScript aus Seiten mit fremdem Domainnamen möglich (Stichwort CORS).

cardo 4.1.1

• Erstmalige Bereitstellung der WFS 3 Implementierung.