Methoden auf Klassen

Ressourcen können Methoden beinhalten. Hier folgen wir den REST-Konventionen mit der Erweiterung ‚method':

• rest.i-ag.ch/{Klasse}/method/{method-name}
• rest.i-ag.ch/{Klasse}/{id}/method/{method-name}

Ersteres ist eine allgemeine Method, z.B. Nachrechnen aller Lagerbestände. Zweites ist eine Methode auf einem bestimmten Datenobjekt mit der ID <id>, also z.B. das Verbuchen einer bestimmten Rechnung.

Methoden können über GET, POST und PUT aufgerufen werden. Aktuell wird nur nach sicheren (es werden keine Daten verändert) und unsicheren Methoden (mit Datenänderung) unterschieden.

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.

Unsichere Methoden werden über POST und PUT aufgerufen, die Parameter werden im Body analog zum Update und Create übergeben.

Der Einfachheit halber wird aktuell nicht nach Idempotenz unterschieden, POST und PUT werden in der API gleich behandelt.

Metadaten

Die Metadaten der Methoden können abgefragt werden, indem das Schlüsselwort "model" an den GET-Aufruf angehängt wird: 

• rest.i-ag.ch/{Klasse}/model (gibt alle Methoden der Klasse aus)
  
• rest.i-ag.ch/{Klasse}/method/{method-name}/model
• rest.i-ag.ch/{Klasse}/{id}/method/{method-name}/model

Methoden werden über folgende Attribute beschrieben:

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.

Folgende Varianten sind möglich:

• URL & form-encoded: Wiederholung der Parameter-Sets mit identischen Namen:  
      "paramA=1&paramB=2&paramA=3&paramB=5" 
• URL & form-encoded: Wiederholung der Parameter-Sets mit indizierten Namen (ab Rev. 28507):  
      "paramA-0=1&paramB-0=2&paramA-1=3&paramB-1=5"
• JSON: Die Parameter-Sets werden als Objekte in einem Array übergeben (ab Rev. 28507):
      [ 
          { 
            "paramA": 1,
            "paramB": 2 
          },
          { 
            "paramA": 3,
            "paramB": 5 
          }
      ] 

Beispiel: Berechnung der VK-Preise von 2 Artikeln in einem Aufruf:

Url: http://localhost:8084/rest2/ArtikelMethods/method/GetArtPriceSell?ArticleID=8&CustomerID=0&Quantity=1&Date=2015-07-01&ArticleID=3&CustomerID=0&Quantity=1&Date=2015-07-01

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]]
    }]
}