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:
...
{
"ABCEinteilung":"2",
"Name":"abc"
}
Sollen gleichzeitig Detaildatensätze respektive Substrukturen übergeben werden, so muss das in folgender Form geschehen:
{
"<Attribut-Name>":"<Attribut-Wert>",
"<Attribut-Name>":"<Attribut-Wert>",
.....
"<Entität-Name>": [
{
"<Attribut-Name>":"<Attribut-Wert>",
"<Attribut-Name>":"<Attribut-Wert>" ,
......
}
]
...
Konkret im Beispiel eines Updates auf einen Kurs mit 2 Unterlisten zu Grundausbildungen und Anstellungsarten sieht es so aus:
{
"BildungsschwerpunktID": 13,
"GrundausbildungListe": [
{
"StichwortID": 7
},
{
"StichwortID": 7
}
],
"AnstellungsartListe": [
{
"StichwortID": 1
},
{
"StichwortID": 2
},
{
"StichwortID": 3
}
]
}
...
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 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. Definiert werden sie in der Liste der Parameter.
...
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.
...
Der meta-Bereich wird für beschreibende Informationen zu der ausgeführten Operation und/oder den Daten verwendet. Darin stehen z.B. die Feldnamen bei Abfragen, sowie weiterführende Links zu abhängigen Daten.Werden nur die Meta-Daten abgefragt (/model), ist der data-Bereich leer.
Lookups und Referenzen
Es gibt Felder, die nur gewisse Werte als Eingabe erlauben. Das sind typischerweise Status- und Typen-Felder. Im Backend sind diese oft als Aufzählungstypen implementiert, in der Datenbank als Integer, im JSON als allgemeine Zahl.
Bei diesen Feldern wird in den Meta-Daten der Properties und der Parametern ein Lookup-Block ausgegeben, der als Array von Key-Value-Paaren implementiert ist. dieser gibt vor, welche Werte erlaubt sind (= Key), und was sie bedeuten (= Value). Diese Informationen können z.B. zum Abgleich von Stammdaten, zur Benutzerführung und für Eingabevalidierungen eingesetzt werden.
Bei Methodenparametern können Fremdschlüssel vorkommen, die in der Schnittstelle in der Regel als Zahl/Integer definiert sind. Damit der Entwickler weiss, wie er z.B. einen Suchdialog aufbauen muss, wird die Eingenschaft "resource" ausgegeben, analog zu den Links,
Die Rückgabe-Struktur für Entitäten sieht wie folgt aus:
{
"resource": [{
"type": "<Resourcentyp "object">",
"meta": {
"name": "<Entität-Name im Kontext der Abfrage>",
"description": "<Beschreibung>",
"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>",
"lookup": [ // optional
{
"key": <Wert>,
"value": <Benutzertext>
},{
.......
}],
"links": [
{
"resource": "<Entität-Name ohne Kontext>",
"cardinality": <Kardinalität 1|2147483647>,
<Wiederholung des Meta-Elements> // nur nächste ebene, keine Rekursion.
}]
},{
.......
}]
}
"data": [<Array mit den Daten gemäss Properties>]
}]
}
Die Rückgabe-Struktur für Views sieht wie folgt aus:
{
"resource": [{
"type": "<Resourcentyp "object">",
"meta": {
"name": "<Entität-Name im Kontext der Abfrage>",
"description": "<Beschreibung>",
"properties": [ // analog zu den Entitäten
{
......
}],
"parameters": [
{
"name": "<Parameter-Name>",
"description": "<Beschreibung>",
"required": <Ist Pflichtfeld [true|false>, // optional
"type": "<Feldtyp number|string|object|boolean|datetime|base64>",
"cardinality": <Kardinalität 1|2147483647>,
"lookup": [ // optional
{
"key": <Wert>,
"value": <Benutzertext>
},{
.......
}]
},{
.......
}]
}
"data": [<Array mit den Daten gemäss den Propterties>]. // Die data-Struktur entspricht exakt derjenigen der properties-Elementen, inkl. Verschachtelung.
}]
}
Die Rückgabe-Struktur für Methoden sieht wie folgt aus:
{
"resource": [{
"type": "<Resourcentyp "object">",
"meta": {
"name": "<Entität-Name im Kontext der Abfrage>",
"description": "<Beschreibung>",
"parameters": [
{
"name": "<Parameter-Name>",
"description": "<Beschreibung>",
"required": <Ist Pflichtfeld [true|false>, // optional
"type": "<Feldtyp number|string|object|boolean|datetime|base64>",
"cardinality": <Kardinalität 1|2147483647>,
"lookup": [ // optional
{
"key": <Wert>,
"value": <Benutzertext>
},{
.......
}],
"resource": <Name der Resource, um bei Referenzwerten Eingabehilfen aufbauen zu können> // optional
},{
.......
}]
}
"data": [<Array mit den Daten gemäss den Parametern>].
}]
}
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.
...