Serialisierung

In der REST API muss an verschiedenen Stellen Inhalt von und nach JSON serialisiert und deserialisiert werden.

Grundsätzlich ist das Format für die Serialisierung (Lesen von der API) dasselbe wie für die Deserialisierung (Schreiben via API).

Primitive Typen

Primitive Datentypen, welche eine entsprechende Repräsentation in JSON haben, wie z.B. Integers oder Strings, werden direkt zwischen Python und JSON übersetzt. Ein Python string aus GEVER wird also als JSON-String ausgegeben, und umkekehrt.

Datum / Zeit

Da JSON keinen nativen Support für datetimes bietet, werden Python/Zope datetimes zu ISO 8601 Strings serialisiert. Als Zeitzone wird bei der Serialisierung immer UTC verwendet, nicht Lokalzeit.

Python	JSON
time(19, 45, 55)	'19:45:55'
date(2015, 11, 23)	'2015-11-23'
datetime(2015, 11, 23, 19, 45, 55, tzinfo=pytz.timezone('Europe/Zurich'))	'2015-11-23T18:45:55+00:00'
DateTime('2018/08/09 13:43:27.261730 GMT+2')	'2018-08-09T11:43:58+00:00'

Dateien

Download (Serialisierung)

Für den Download von Dateien wird ein File-Field zu einem Mapping serialisiert welches die wichtigsten Metadaten zur Datei (nicht zum Dokument), und einen Download-Link für das Herunterladen enthält:

{
  "@id": "http://example.org/dossier/mydoc",
  "@type": "opengever.document.document",
  "title": "My document",
  "...": "",
  "file": {
    "content-type": "application/pdf",
    "download": "http://example.org/dossier/mydoc/@@download/file",
    "filename": "file.pdf",
    "size": 74429
  }
}

Die URL im download Property zeigt auf die reguläre Download-View von Plone. Dies bedeutet, dass der Client einen GET request auf diese URL durchführen kann, um die Datei herunterzuladen. Jedoch darf hier als Accept Header nicht mehr application/json gesetzt werden (wie sonst für API-Requests üblich), sondern der MIME-Type der zu herunterladenden Datei (gemäss dem content-type Property).

Upload (Deserialisierung)

Für Datei-Felder muss der Client die Datei und deren Metadaten als ein Mapping senden, ähnlich dem Mapping für den Download. Das Mapping muss die Daten der Datei base64 codiert im data Property enthalten, und weitere Metadaten in den übrigen Properties:

• data - der Inhalt der Datei, base64 codiert
• encoding - das Encoding das verwendet wurde, also base64
• content-type - der MIME-Type der Datei
• filename - der Dateiname, inkl. Dateiendung

{
  "@type": "opengever.document.document",
  "title": "My file",
  "...": "",
  "file": {
      "data": "TG9yZW0gSXBzdW0uCg==",
      "encoding": "base64",
      "filename": "lorem.txt",
      "content-type": "text/plain"}
}

Verweise

Serialisierung

Verweise werden zu einer summarischen Repräsentation des referenzierten Objekts serialisiert:

{
  "...": "",
  "relatedItems": [
    {
      "@id": "http://example.org/dossier/doc1",
      "@type": "opengever.document.document",
      "UID": "efb7c240392e49a9a23ba8f51ce0175c",
      "title": "Document 1",
      "description": "Description"
    }
  ]
}

Die Liste von Verweisen wird zu einer einfachen JSON-Liste serialisiert.

Deserialisierung

Um beim Erstellen oder Updaten von Objekten einen Verweis zu setzen, können verschiedene Methoden verwendet werden um das Verweisziel anzugeben. Es kann einer der hier aufgeführten Bezeichner verwendet werden, um das Verweisziel eindeutig zu identifizieren:

Typ	Beispiel
UID	'9b6a4eadb9074dde97d86171bb332ae9'
IntId	123456
Pfad	'/dossier/doc1'
URL	'http://example.org/dossier/doc1'