RESTful web API

Hinweise:

• Für die Version 1, lest bitte: das shackspace wiki.
• Die Aktuelle Version ist 2

Version 2:

URLs

Es stehen folgende URLs zu Verfügung:

• standby.shack/2/light
  • adressiert alle schaltbaren Lichter
• standby.shack/2/light/<licht ID>
  • adressiert ein spezielles Licht (<licht ID> muss mit einer Nummer wie in Licht IDs beschrieben ausgewechselt werden)
• standby.shack/2/<room>
• standby.shack/2/<room>/<light group>
• standby.shack/2/<room>/<light group>/<id in group>
  • Auch die Gruppen ID's und ID's innerhalb einer Nummer können Licht IDs entnommen werden.

HTTP Methoden

Folgende HTTP-Request Methoden sind erlaubt:

• GET
  • liefert den Status des adressierten Lichtes aus (Adressierung siehe URLs)
• PUT
  • setzt den Status der adressierten Lichter (Adressierung siehe URLs)

content-type

Folgende MIME-Types oder content-types sind unterstützt:

• application/json
  • ist bei GET die Standard annahmen, wenn kein Accept: <MIME-Type> header gesendet wurde.
  • für den aufbau der JSON strings lest bitte: JSON Format
• text/plain
  • für den aufbau von plain text lest bitte: Plain Text

Hinweis: Wenn weitere MIME-Types unterstützt werden sollen, wendet euch bitte einfach an mich oder schreibt selber ein erlang,java oder c Modul, was den entsprechenden MIME-Type handelt(wenn ihr genaueres wissen wollt, wie das geht sprecht mich an)

Beispiel Abfragen:

Erst einmal ein paar valide GET Abfragen:

$ curl -H "Accept: application/json" standby.shack/2/light/
{"type":"states","124":0,"106":0,"115":0,"119":0,"105":0,"117":0,"107":0,"108":0,"109":0,"121":0,"103":0,"126":0,"125":0,"116":0,"112":0,"120":0,"110":0,"123":0,"113":0,"118":0,"122":0,"104":0,"101":0,"111":0,"114":0,"100":0,"102":0}

$ curl -H "Accept: application/json" standby.shack/2/light/123
{"type":"states","123":0}

$ curl -H "Accept: text/plain" standby.shack/2/light
124 0
106 0
115 0
119 0
105 0
117 0
107 0
<und so weiter>

$ curl -H "Accept: text/plain" standby.shack/2/light/123
123 0

Ein paar invalide GET-Requests:

$ curl -H "Accept: text/plain" standby.shack/2/light/affe
can't convert url

$ curl -H "Accept: text/plain" standby.shack/2/light/90000
can't get lights

$ curl -H "Accept: text/plain" standby.shack/2/lights
can't convert url

$ curl -H "Accept: application/json" standby.shack/2/light/affe
{"type":"error","error":"can't convert url"}

$ curl -H "Accept: application/json" standby.shack/2/light/90000
{"type":"error","error":"can't get lights"}

$ curl -H "Accept: application/json" standby.shack/2/lights
{"type":"error","error":"can't convert url"}

Ein paar valide PUT-Requests:

Schaltet alle Lichter ein:

$ curl -v -X PUT -H "content-type: application/json" standby.shack/2/light/ -d '{"type":"set","state":1}'
...
> PUT /2/light/ HTTP/1.1
...
> content-type: application/json
...
< HTTP/1.1 204 No Content
...

$ curl -v -X PUT -H "content-type: text/plain" standby.shack/2/light -d '1'

Schaltet den Zustand aller Lichter um:

$ curl -v -X PUT -H "content-type: application/json" standby.shack/2/light/ -d '{"type":"toggle"}'
$ curl -v -X PUT -H "content-type: text/plain" standby.shack/2/light -d 't'

Schaltet die Lampe mit der ID 120 aus:

$ curl -v -X PUT -H "content-type: application/json" standby.shack/2/light/120 -d '{"type":"set","state":0}'
$ curl -v -X PUT -H "content-type: text/plain" standby.shack/2/light/120 -d '0'

Schaltet den Zustand des Lichtest 113 um:

$ curl -v -X PUT -H "content-type: application/json" standby.shack/2/light/113 -d '{"type":"toggle"}'
$ curl -v -X PUT -H "content-type: text/plain" standby.shack/2/light/113 -d 't'

Nicht zulässige PUT-Requests:

Bei nicht zulässigen PUT-Requests auf die API wird immer der Response-Code 422 Unprocessable Entity zurück gegeben:

$ curl -v -X PUT -H "content-type: text/plain" standby.shack/2/light/ff113 -d '24'
...
> PUT /2/light/ff113 HTTP/1.1
...
< HTTP/1.1 422 Unprocessable Entity
...

Requests mit einen nicht unterstützten MIME-Type

Bei Requests mit einen nicht unterstützten MIME-Type wird bei PUT-Requests der Response-Code 415 Unsupported Media Type zurück gegeben und bei GET-Requests 406 Not Acceptable:

$ curl -v -X PUT -H "content-type: text/html" standby.shack/2/light/113 -d '1'
...
< HTTP/1.1 415 Unsupported Media Type
...

$ curl -v -H "Accept: text/html" standby.shack/2/light/113
...
< HTTP/1.1 406 Not Acceptable
...