...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
CRUD
Die CRUD-Operationen werden über folgende HTTP-Verben unterstützt:
...
- Jedes Objekt ist im Kontext der Klasse mit einer eindeutigen Id identifizierbar: rest.i-ag.ch/{Klasse}/{ID}.
- Beim Update (PUT) und Löschen (DELETE) ist die Syntax mit der ID zwingend.
- Beim Insert (POST) ist keine ID erlaubt, es kann jedoch kann ein Vater-Objekt angegeben werden, um Kind-Elemente anzufügen: rest.i-ag.ch/{Klasse}/{ID}/{Klasse}.
- Nutzdaten werden beim Insert (POST) und Update (PUT) im Body übergeben.
- Lesend (GET) kann die komplette Baumstruktur des Objektmodells verwendet werden: rest.i-ag.ch/{Klasse}/{ID}/{Kind-Klasse}/{ID}/…
Bsp. Mehrwertsteuerdetails zum Aufwandkonto der Adresse mit der Id 123: ./Adresse/123/KontoAufwand/MWSTToOne.
Beispiele
Lese Land 1
GET auf http://rest.i-ag.ch/Land/1
...
DELETE auf http://rest.i-ag.ch/Land/10
Antwort: 200 Ok ohne Body
Queries auf Klassen
Beim Lesen (GET-Operation) besteht die Möglichkeit, Daten über Filterparameter einzuschränken:
...
Dies gibt von alle Einträgen der Ländertabelle von ID 1 bis ID 100 die Felder ID und Bezeichnung zurück.
Views
Für komplexe Fälle reicht dies aber nicht mehr. In einem solchen Fall wird die View näher spezifiziert:
...
Eine Paging-Funktionalität ist nicht implementiert. Eine analoge Funktionalität kann mit den Sortier-Optionen und einer Einschränkung auf die maximale Anzahl Datensätze erreicht werden.
Datentypen (interne Info)
Bei berechneten Felder kann der Datentyp nicht ohne zusätzliche Information in der Abfrage bestimmt werden. Standardmässig werden alle berechneten Felder als String ausgegeben.
...
->Unittestparent.grouped(
TextVal groupby;
nb := group.count(TextVal); {$define nb vtInteger1}
bv := group.avg(BoolVal); {$define bv vtBoolean}
dv := group.min(DateVal); {$define dv vtDateTime}
iv := group.min(IntVal); {$define iv vtInteger2}
cv := group.min(CurVal); {$define cv vtFloat8}
);
Methoden auf Klassen
Ressourcen können Methoden beinhalten. Hier folgen wir den REST-Konventionen mit der Erweiterung ‚method':
...
Die Struktur der Antwort ist identisch zu derjenigen der CRUD-Operationen. Einziger Unterschied ist, dass die "properties"-Sektion durch eine "parameters"-Sektion ersetzt ist.
Gemäss http-Standards wird für die sicheren Methoden ein GET-Aufruf verlangt, allfällige Parameter werden in der URL mitgegeben.
...
Der Einfachheit halber wird aktuell nicht nach Idempotenz unterschieden, POST und PUT werden in der API gleich behandelt.
Parameterübergabe
Die Parameter können in folgenden Varianten übergeben werden:
- GET: In der URL form-encoded
- PUT/POST:
- Form-encoded: Im Content
- JSON: als einfaches Objekt (ab Rev. 28507).
Mehrfacher Methoden-Aufruf in einem REST-Aufruf
Zur Leistungsoptimierung können Methoden mit unterschiedlichen Argumenten in einem Aufruf mehrfach aufgerufen werden, indem die Argumente mehrfach übergeben werden. Die Resultate werden in der Data-Sektion der Antwort in derselben Reihenfolge ausgegeben wie die Argumente übergeben worden sind.
...
Antwort:
{
"resource": [{
"type": "object",
"meta": {
"name": "GetArtPriceSell",
"description": "",
"parameters": [{
"name": "Price",
"desciption": "",
"required": true,
"type": "number",
"cardinality": 1,
"direction": "out"
},
{
"name": "PriceType",
"desciption": "",
"required": true,
"type": "number",
"cardinality": 1,
"direction": "out"
}]
},
"data": [[4.9,40],[38,40]]
}]
}
Meta-Daten
| Anchor | ||||
|---|---|---|---|---|
|
Die Meta-Daten, also Feldnamen und Feldtypen lassen sich über die folgende URI abfragen:
...
Das Format der Metadaten wird analog zu den Nutzdaten von Client angefordert.
Beispiel JSON: Tabelle Adresse: rest.i-ag.ch/Adresse/model
{
"resource": [{
"meta": {
"name": "Adresse",
"description": "",
"type": "object",
"properties": [
{
"name": "ID",
"description": "",
"primary": true,
"required": true,
"type": "number"
},{
"name": "ABCEinteilung",
"description": "ABC-Einteilung",
"type": "number"
},{
"name": "AbladevorschriftID",
"description": "Abladevorschrift",
"type": "number",
"links": [
{
"name": "Abladevorschrift",
"resource": "Abladevorschrift",
"cardinality": 1
}]
},{
"name": "AdresseIDNachfolger",
...
...
Die Metadaten werden so weit als möglich nach Draft 04 von json-schema.org aufgebaut, eine Norm existiert zurzeit noch nicht.
Rückgabestatus und Fehlercodes
Jede Antwort vom Server wird mit einem Statuscode zurückgegeben. Bei Fehlern wird zusätzlich ein Detailtext zurückgegeben, der genauere Auskunft über die Ursache gibt. Folgende Codes sind implementiert:
...