Operationen

Die möglichen Operationen auf der API sind auf HTTP Verben gemappt.

Verb	URL	Operation
GET	/{path}	Gibt die Attribute eines Objekts zurück
POST	/{container}	Erstellt ein neues Objekt in dem entsprechenden Container
PATCH	/{path}	Aktualisiert einzelne Attribute eines Objekts

Inhalte lesen (GET)

Mit einem GET Request auf die URL eines Objekts können die Daten (Metadaten wie auch Primärdaten) eines Objekts ausgelesen werden.

Im Fall eines Objekts das “folderish” ist (ein Container), gibt es ein spezielles Attribut items, welches eine summarische Auflistung der Unterobjekte enthält (direkte children des Objekts).

GET /(path)

Liefert die Attribute des Objekts unter path zurück

Beispiel-Request:

GET /ordnungssystem/fuehrung/dossier-23 HTTP/1.1
Accept: application/json

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",
  "UID": "66395be6595b4db29a3282749ed50302",
  "archival_value": "not archival worthy",
  "archival_value_annotation": null,
  "classification": "unprotected",
  "comments": null,
  "container_location": null,
  "container_type": null,
  "created": "2016-01-08T09:51:40+01:00",
  "custody_period": 30,
  "date_of_cassation": null,
  "date_of_submission": null,
  "description": "",
  "end": null,
  "filing_prefix": null,
  "former_reference_number": null,
  "keywords": [],
  "items": [
    {
      "@id": "https://example.org/ordnungssystem/fuehrung/dossier-23/document-259",
      "@type": "opengever.document.document",
      "description": null,
      "title": "Ein Dokument"
    },
    {
      "@id": "https://example.org/ordnungssystem/fuehrung/dossier-23/document-260",
      "@type": "opengever.document.document",
      "description": null,
      "title": "Ein weiteres Dokument"
    }
  ],
  "modified": "2016-01-19T11:15:22+01:00",
  "number_of_containers": null,
  "parent": {
    "@id": "https://example.org/ordnungssystem/fuehrung",
    "@type": "opengever.repository.repositoryfolder",
    "description": null,
    "title": "Führung"
  },
  "privacy_layer": "privacy_layer_no",
  "public_trial": "unchecked",
  "public_trial_statement": null,
  "reference_number": null,
  "relatedDossier": null,
  "responsible": "john.doe",
  "retention_period": 5,
  "retention_period_annotation": null,
  "review_state": "dossier-state-active",
  "start": "2016-01-08",
  "temporary_former_reference_number": null,
  "title": "Ein Geschäftsdossier"
}

Code-Beispiel (Python)

url = 'https://example.org/ordnungssystem/fuehrung/'
response = session.get(url)
title = response.json()['title']

Inhalte erstellen (POST)

Um ein neues Objekt zu erstellen, muss ein POST Request auf den Container, der das Objekt enthalten soll, gemacht werden. Die ID des erstellten Objekts (z.B. ‘document-26’) wird vom System selbst mitbestimmt und muss nicht mitgegeben werden.

POST /(container)

Erstellt ein neues Objekt innerhalb von container.

Beispiel-Request:

POST /ordnungssystem/fuehrung HTTP/1.1
Accept: application/json

{
  "@type": "opengever.dossier.businesscasedossier",
  "title": "Ein neues Geschäftsdossier",
  "responsible": "john.doe",
  "custody_period": 30,
  "archival_value": "unchecked",
  "retention_period": 5
}

Beispiel-Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://example.org/ordnungssystem/fuehrung/dossier-24

null

Im Location Header der Response ist die URL des neu erstellen Objekts zu finden.

Code-Beispiel (Python)

dossier_data = {
    "@type": "opengever.dossier.businesscasedossier",
    "title": "Ein neues Dossier via API",
    "responsible": "peter.muster",
    "custody_period": 30,
    "archival_value": "unchecked",
    "retention_period": 10,
}

url = 'https://example.org/ordnungssystem/fuehrung/'
response = session.post(url, json=dossier_data)
new_dossier_url = response.headers['Location']

Inhalte bearbeiten (PATCH)

Um ein oder mehrere Attribute eines Objekts zu aktualisieren, wird ein PATCH Request verwendet.

PATCH /(path)

Aktualisiert ein oder mehrere Attribute des Objekts unter path.

Beispiel-Request:

PATCH /ordnungssystem/fuehrung/dossier-24 HTTP/1.1
Accept: application/json

{
  "title": "Ein umbenanntes Dossier"
}

Beispiel-Response:

HTTP/1.1 204 No Content

null

Code-Beispiel (Python)

dossier_data = {
    "title": "Neuer Titel"
}

url = 'https://example.org/ordnungssystem/fuehrung/dossier-42'
response = session.patch(url, json=dossier_data)