Grundlagen¶

Die OneGov GEVER API ist eine RESTful HTTP API.

Dies bedeutet, dass Operationen über die API via HTTP Requests durchgeführt werden, welche von einem HTTP Client abgesetzt werden.

HTTP ist ein Protokoll für die Kommunikation zwischen einem Client und einem Server, und basiert auf dem Austausch von Anfragen des Clients (Request) und Antworten des Servers (Response).

Die Verwendung der API funktioniert so, dass Requests auf die URL des entsprechenden Inhaltsobjekts gemacht werden, aber ein spezieller HTTP-Header verwendet wird welchen den Request als API-Request auszeichnet (um ihn von einem Request eines normales Browsers abzugrenzen).

Für die meisten Requests ist es notwendig, dass sich der Benutzer zuerst an der API authentisiert, siehe dazu das Kapitel zur Authentisierung.

Änderungen an der API werden im API Changelog dokumentiert.

Request¶

Requests an die API setzen sich zusammen aus einem HTTP Verb, einer URL, Request-Headern, und für gewisse Typen von Requests, einem Request-Body im JSON Format.

HTTP Verb¶

Im Kapitel Operationen ist beschrieben, auf welche HTTP Verben die verfügbaren Operationen gemappt sind.

URL¶

Die URL eines Requests ist bestimmt durch das Objekt, für welches eine Operation durchgeführt werden soll. Diese URL ist in der Regel für das entsprechende Objekt in der Adresszeile des Browsers sichtbar.

Headers¶

Die API verwendet JSON für die Serialisierung von Daten (für die Eingabe wie auch die Ausgabe).

Dementsprechend muss bei der Anfrage (Request) der HTTP-Header Accept: application/json gesetzt werden, damit ein Request an die API weitergeleitet wird.

Beispiel-Request:

GET /ordnungssystem HTTP/1.1
Accept: application/json

Dieser Header muss bei jedem Request auf die API gesetzt werden, und wird in den folgenden Beispielen daher nicht mehr immer explizit erwähnt.

Body¶

Bestimmte Request-Typen (POST und PATCH) brauchen weitere Informationen, welche in Form eines Request-Bodies im JSON Format mitgegeben werden. Wie der Inhalt dieses Bodies genau beschaffen sein muss, ist im Kapitel Operationen beschrieben.

Response¶

Wenn eine Response einen Body hat, ist dies immer ein JSON-Dokument:

Beispiel-Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
   "@context": "http://www.w3.org/ns/hydra/context.jsonld",
   "@id": "https://example.org/ordnungssystem/fuehrung/dossier-23",
   "@type": "opengever.dossier.businesscasedossier",
   "oguid": "fd:12345",
   "title": "Titel des Objekts",
   "review_state": "dossier-state-active",
    "...": "..."
}

(Gekürzt - vollständige Beispiele von konkreten Responses sind in späteren Abschnitten zu finden)

Die mit einem @ Zeichen präfixten Keys haben eine spezielle Beduetung, und entsprechen nicht einem Feld auf dem Inhaltstyp, sondern sind JSON-LD (Linked Data) Metadaten:

Key	Bedeutung	Beschreibung
`@context`	Kontext	Wird immer denselben Wert haben, eine URI zum Hydra Kontext - dieser Key hat für die OneGov GEVER API im Moment keine Relevanz.
`@id`	Eindeutige URL	Die eindeutige URL zu einem Objekt.
`@type`	Typ eines Objekts	Der Typ eines Objekts. Dieser Typ entspricht einem der unter Inhaltstypen angegebenen Typen, und lässt den Client so wissen, welche Felder mit welchen Datentypen in einer Antwort zu erwarten sind.

Zusätzlich zu den oben aufgeführten JSON-LD Attributen gibt es für Objekttypen, welche einen Workflow haben, ein allgemeines Property review_state, welches den aktuellen Workflow-State enthält:

Key	Bedeutung	Beschreibung
`review_state`	Workflow-State	Falls das Objekt einen Workflow hat, enthält dieses Property den aktuellen Worflow-State.

Siehe Workflow für Details bezüglich Workflows.