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",
  "container_location": null,
  "container_type": null,
  "created": "2016-01-08T10:51:40+00: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,
      "is_subdossier": null,
      "title": "Ein Dokument"
    },
    {
      "@id": "https://example.org/ordnungssystem/fuehrung/dossier-23/document-260",
      "@type": "opengever.document.document",
      "description": null,
      "is_subdossier": null,
      "title": "Ein weiteres Dokument"
    }
  ],
  "modified": "2016-01-19T11:15:22+00:00",
  "number_of_containers": null,
  "oguid": "fd:12345",
  "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']

Erweiterbare Komponente (Expansion)

Eine erweiterbare Komponente (auch “Expansion” genannt) ist ein Mechanismus, um in einem GET-Request einer Ressource weitere Information anzufordern, z.B. die Navigation, Breadcrumbs, etc. Damit kann verhindert werden, dass ein weiterer Request abgesetzt werden muss, um diese Angaben abzuholen. Weitere Informationen zu diesem Mechanismus findet man unter https://plonerestapi.readthedocs.io/en/latest/expansion.html.

Die erweiterbaren Komponenten können über den Parameter expand in die Response eingebettet werden.

Folgende erweiterbaren Komponente stehen zur Verfügung und sind in den entsprechenden Kapiteln beschrieben:

Eine weitere erweiterbare Komponente erlaubt es, Informationen zum Hautpdossier einer Ressource abzufragen.

Beispiel-Request:

GET /ordnungssystem/dossier/subdossier/document?expand=main-dossier HTTP/1.1
Accept: application/json

Beispiel-Response:

HTTP/1.1 200 OK

{
  "@components": {
    "main-dossier": {
      "@id": "https://example.org/ordnungssystem/dossier",
      "@type": "opengever.dossier.businesscasedossier",
      "UID": "c526b9caf83449eca1ac8e0b985cc92b",
      "description": "",
      "is_leafnode": null,
      "is_subdossier": false,
      "review_state": "dossier-state-active",
      "title": "Gesetzesentwürfe"
    },
  },
  "@id": "https://example.org/ordnungssystem/dossier/subdossier/document?expand=main-dossier",
  "..."
}

Falls die Frage, welches das Hauptdossier einer Ressource ist, nicht beantwortet werden kann, dann ist der Wert in der Response nicht definiert.

Beispiel-Request:

GET /ordnungssystem?expand=main-dossier HTTP/1.1
Accept: application/json

Beispiel-Response:

HTTP/1.1 200 OK

{
  "@components": {
    "main-dossier": null,
  },
  "@id": "https://example.org/ordnungssystem?expand=main-dossier",
  "..."
}

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)

Inhalte löschen (DELETE)

Um ein Objekt zu löschen, wird ein DELETE Request verwendet. Dies ist grundsätzlich in GEVER verboten und in teamraum erlaubt.

DELETE /(path)

Löscht das Objekt unter path.

Beispiel-Request:

DELETE /workspaces/workspace-1/document-24 HTTP/1.1
Accept: application/json

Beispiel-Response:

HTTP/1.1 204 No Content

null
Code-Beispiel (Python)
url = 'https://example.org/workspaces/workspace-1/document-24'
response = session.delete(url)