Codierung der Daten
Alle zu übermittelnden Daten müssen im ASCII-Format und HTTP-konform übertragen werden.
Folgende Daten-Konvertierung ins ASCII-Format wird erwartet:
Datentyp | Format |
---|---|
Zeichenketten | Ersetzen der reservierten Zeichen gemäss Übergabeformat / HTTP-Standard |
Binär | base64-Codierung |
Datumswerte | ISO 8601 |
Boolean | True/False |
Zahlen | Dezimaltrennzeichen Punkt, keine weiteren Formatzeichen |
URL-Encoded
Content-type: application/x-www-form-urlencoded
Accept: -
...
Die Nutzdaten werden als JSON-Objekt in Form von Name-Wert-Paaren übergeben. In der einfachen Form sieht das so aus:
Daten:
{
"ABCEinteilung":"2",
"Name":"abc"
}
Sollen gleichzeitig Detaildatensätze respektive Substrukturen übergeben werden, so muss das in folgender Form geschehen:
{
"<Attribut-Name>":"<Attribut-Wert>"
"childList": [
{
"meta": {
"name": "<Entität-Name>",
"parameters": [
{
"name": "<Parameter-Name>",
},{
...
...
}],{
}
" "childList": [
{....}]
}
}
"data": [<Array mit den Daten gemäss properties>Parameter>]
},
{
"meta":...
...
}]
}
Das Element childList entspricht in der Struktur exakt dem resource-Element für Methoden-Aufrufe. Diese Elemente können beliebig tief verschachtelt werden, müssen aber zwingend dem Datenmodel entsprechen, d.h die logische Verbindung zwischen den Elementen muss definiert sein, und zwar immer vom übergeordneten Element zum untergeordneten:
So kann einer Adresse ein Auftrag übergeben werden, und dem Auftrag Positionen. Einem auftrag kann aber keine Adresse mitgegeben werden, da der Auftrag von der Adresse abhängig ist.
Konkret im Beispiel eines Updates auf einen Kurs mit 2 Unterlisten zu Grundausbildungen und Anstellungsarten sieht es so aus:
{
"BildungsschwerpunktID":"13",
"childlist": [
{
"meta": {
"name": "GrundausbildungListe",
"parameters": [{
"name": "StichwortID"
}]
},
"data": [[7], [8]]
},
{
"meta": {
"name": "AnstellungsartListe",
"parameters": [{
"name": "StichwortID"
}]
},
"data": [[1], [2], [3]]
}
]
}
...
Als Konsequenz werden mit einer leeren Daten-Liste alle vorhandenen Einträge gelöscht:
…
"name": "AnstellungsartListe",
"parameters": [{
"name": "StichwortID"
}]
},
"data": []
…
Ist dies nicht gewollt und die vorhandene Liste soll nicht verändert werden, darf die Substruktur nicht übergeben werden.
...
Die generelle Rückgabe-Struktur sieht wie folgt aus:
{
"resource": [{
"type": "<Resourcentyp "object">",
"meta": {
"name": "<Entität-Name im Kontext der Abfrage>",
"description": "<Beschreibung>",
"parameters": [ Nur bei Views und Methoden
{
"name": "<Parameter-Name>",
"description": "<Beschreibung>",
"required": <Ist Pflichtfeld [true|false], optional>,
"type": "<Feldtyp number|string|object|boolean|datetime|base64>"
"cardinality": <Kardinalität 1|2147483647>
},{
...
...
}],
"properties": [
{
"name": "<Element-Name>",
"description": "<Beschreibung>",
"primary": <Ist Primärschlüssel [true|false], optional>,
"required": <Ist Pflichtfeld [true|false], optional>,
"type": "<Feldtyp number|string|object|boolean|date-time|base64>"
"links": [
{
"resource": "<Entität-Name ohne Kontext>",
"cardinality": <Kardinalität 1|2147483647>,
<Wiederholung des Meta-Elements> Bei Model-Abfragen wird vom Meta-Element nur der Name zurückgegeben, da der Baum je nach Datenmodell ansonsten ins Unendliche wächst.
}]
},{
...
...
}]
}
"data": [<Array mit den Daten gemäss properties>] Bei Elementen mit Detail-Datensätzen wird der Element-Wert als Array mit 2 Werten ausgegeben, dem Feldwert und einem Array mit den Detaildatensatz-Arrays. Die data-Struktur entspricht exakt derjenigen des properties-Elements.
}]
}
Fehlermeldungen werden in einem analogen Format zurückgegeben:
{
"resource": [{
"type": "<Resourcentyp „message">",
"code": "<ErrorCode mit Errortext>",
"message": "<Detailtext>"
}]
}
Die resource-Elemente können sich wiederholen, wenn unterschiedliche Daten-Strukturen in einem Aufruf übergeben werden.
Beispiel einer komplexen Abfrage einiger Adress-Daten, Attributen des Aufwandkontos und der hinterlegten MWST-Details, sowie der vorhandenen Belege der Adresse 1181:
{
"resource" : [{
"type" : "object",
"meta" : {
"name" : "Adresse",
"description" : "",
"properties" : [{
"name" : "AnredeID",
"description" : "Anrede",
"type" : "number"
}, {
"name" : "Name",
"description" : "Name",
"type" : "string"
}, {
"name" : "Name2",
"description" : "Zweitname",
"type" : "string"
}, {
"name" : "ID",
"description" : "",
"primary" : true,
"required" : true,
"type" : "number",
"links" : [{
"name" : "Beleg",
"resource" : "Beleg",
"cardinality" : 2147483647,
"description" : "",
"type" : "object",
"properties" : [{
"name" : "ArtikelTotal",
"description" : "Artikeltotal",
"type" : "number"
}, {
"name" : "AuftragsNr",
"description" : "Auftrags-Nr.",
"type" : "number"
}, {
"name" : "BelegNr",
"description" : "Nummer",
"type" : "number"
}, {
"name" : "ID",
"description" : "",
"primary" : true,
"required" : true,
"type" : "number"
}, {
"name" : "AdresseID",
"description" : "Adresse",
"type" : "number"
}]
}]
}, {
"name" : "KontoIDAufwand",
"description" : "Vorschlag Aufwandskonto",
"type" : "number",
"links" : [{
"name" : "KontoAufwand",
"resource" : "Konto",
"cardinality" : 1,
"description" : "Vorschlag Aufwandskonto",
"type" : "object",
"properties" : [{
"name" : "Bezeichnung",
"description" : "Bezeichnung",
"type" : "string"
}, {
"name" : "Kontoart",
"description" : "Kontoart",
"type" : "number"
}, {
"name" : "ID",
"description" : "",
"primary" : true,
"required" : true,
"type" : "number"
}, {
"name" : "MWSTID",
"description" : "Vorschlag MWST",
"type" : "number",
"links" : [{
"name" : "MWSTToOne",
"resource" : "MWST",
"cardinality" : 1,
"description" : "Vorschlag MWST",
"type" : "object",
"properties" : [{
"name" : "Aktiv",
"description" : "MWST aktiv",
"type" : "boolean"
}, {
"name" : "Bezeichnung",
"description" : "Bezeichnung",
"type" : "string"
}, {
"name" : "Kuerzel",
"description" : "Kürzel",
"type" : "string"
}, {
"name" : "ID",
"description" : "",
"primary" : true,
"required" : true,
"type" : "number"
}]
}]
}]
}]
}]
},
"data" : [
[null,
"Meine AG",
null,
[1181,
[14835.15, 1024, 11476, 4904, 1181],
[14835.15, 1024, 1024, 4907, 1181],
[42.25, null, 2643, 4914, 1181],
[311.1, null, 2644, 4915, 1181],
[110.3, null, 2645, 4916, 1181]
],
[1000008,
["Einkauf Bier",
3,
1000008,
[2,
[true, "8% MWST", "8%", 2]
]
]
]
]
]
}]
}
Customizing, Modellerweiterungen
...