Webservice (REST)

ScoutNet API Webservice

Die ScoutNet API basiert auf einem Webservice, der RPC im REST-Stil mit JSON als Datenaustauschformat implementiert. Die Funktionsparameter werden JSON-kodiert in der URL übergeben. Der Body der HTTP-Response ist dann eine JSON-kodierte Serialisierung des Ergebnisobjekts. Klingt vielleicht kompliziert, ist aber eigentlich ganz einfach und wird an ein paar Beispielen schnell klar. (Geheimtipp: Wenn man ?beautify an die URL hängt wird die Ausgabe lesbarer formatiert).

Stabile API-Version: 0.2
Die nachfolgenden Angaben beziehen sich auf die stabile Version 0.2. (Version in der URL austauschbar).

Beispiel-Anfragen

Gruppe mit der id 7 (Stamm Tenkterer)

https://api.scoutnet.de/api/0.2/group/7/

Die Termine von Stamm Tenkterer

https://api.scoutnet.de/api/0.2/group/7/events/

Die Leiterrunden von Stamm Gandalf

https://api.scoutnet.de/api/0.2/group/6/events/?json=["'Leiterrunde' in keywords"]

Event mit der id 120574 (falls den noch keiner gelöscht hat)

https://api.scoutnet.de/api/0.2/event/120574/

Mehrere Gruppen (Diözese Köln, Bezirk Bergischland, Stamm Gandalf)

https://api.scoutnet.de/api/0.2/groups/?json=[[4,5,6]]

2 Events

https://api.scoutnet.de/api/0.2/events/?json=[[120574,122887]]

ALLE Events mit Keyword JOTI

https://api.scoutnet.de/api/0.2/events/?json=["'JOTI' in keywords"]

Abfragen einzelner Objekte

Aufbau der URL

  Basis-URL         API-Version  Kind   id des angefragten Objekts
 /          \_____________   |   / \    /
/                         \ / \ /   \  / 
https://api.scoutnet.de/api/0.2/group/7/

Dieser Request entspricht dem Aufruf des folgenden PHP-Codes im PHP-Client:

Code

scoutnet()->group( 7 );

Format des Ergebnisses

Die Rückgabe des webservice ist ein JSON Objekt. Am Feld "kind" erkennt man, dass es sich hier um eine einzelne Gruppe handelt.

Code

{
    "kind":"group",
    "global_id":"7",
    "name":"Stamm Tenkterer",
    "zip":"42699",
    "city":"Solingen",
    "district":"L\u00f6hdorf",
    "internal_id":"10\/01\/08",
    "layer":"unit",
    "federal_state":"Nordrhein-Westfalen",
    "country":"Deutschland"
}

Aufrufen von API Methoden

Methoden des Interfaces ScoutNet_API, siehe die API Dokumentation des PHP clients.

Aufbau der URL

  Basis-URL         API-Version  Methode    Parameterliste (im JSON-Format)
 /          \_____________   |   /  \         /                  \
/                         \ / \ /    \       /                    \
https://api.scoutnet.de/api/0.2/events/?json=["'JOTI' in keywords"]
                                               \                /
                                                PfadiQL-Anfrage

Dieser request entspricht dem Aufrufen des folgenden PHP-Codes:

Code

scoutnet()->events( "'JOTI' in keywords" );

Format des Ergebnisses

Am Feld "kind" erkennt man, dass es sich hier um eine collection, also einer Liste von Objekten handelt, die vom Typ "element_type", hier also "event" sind.

Code

{"kind":"collection",
"element_type":"event",
"elements":{
    "0":{
        "kind":"event",
        "id":"120574",
        "uid":"120574",
        "group_id":"2220",
        "title":"JOTA\/JOTI",
        ...
        "keywords":{"4":"Aktion","242":"JOTA","243":"JOTI"}
    },"1":{
        "kind":"event",
        "id":"122887",
        ...
        "keywords":{"242":"JOTA","243":"JOTI"}
    }
}}

Aufrufen von Methoden einzelner Objekte

Methoden der Interfaces ScoutNet_[X], wobei [X] ein kind ist, also Event, Group, etc., siehe die API Dokumentation des PHP clients.

Aufbau der URL

  Basis-URL         API-Version  Kind  id  Methode    Parameterliste (im JSON-Format)
 /          \_____________   |   / \    / / \         /                         \
/                         \ / \ /   \  / /   \       /                           \
https://api.scoutnet.de/api/0.2/group/3/events/?json=["start_date > '2011-01-01'"]
https://api.scoutnet.de/api/0.2/group/6/parent/
                                                       \____               ____/
                                                            PfadiQL-Anfrage

Diese requests entsprechen dem Aufrufen des folgenden PHP-Codes:

Code

scoutnet()->group(7)->events( "start_date > '2011-01-01'" );
scoutnet()->group(7)->parent();

Es können jedoch nur Methoden aufgerufen werden, die Objekte zurückgeben (wie z.B. parents), nicht einzelne Werte (wie z.B. title). Die Rückgaben sind dann analog zu den weiter oben genannten Beispielen, je nachdem ob die Funktion ein einzelnes Objekt oder eine collection zurückgibt.

Fehler / Exceptions

Zwei Arten von Fehlern können auftreten.

1. Auf dem Server tritt eine unbehandelte Exception auf. In diesem Fall wird statt JSON-Code eine Fehlermeldung zurückgegeben. Die Rückgabe kann somit nicht als JSON geparsed werden. Das müssen Clients des Webservice abfangen.
2. Der Server stellt ungültige Eingaben fest und gibt ein JSON-Objekt folgender Form zurück:

   Code

   {
       "kind":"exception",
       "message":"id muss ein integer sein"
   }

Fragen? Probleme? Anregungen? Beiträge? Oder du willst mithelfen?

Wende dich an Mütze unter muetze(ät)scoutnet.de.