Mit einem REST-Dienst sprechen
Eine Aufgabenliste für dein Team, die nicht in der Welt liegt, sondern auf einem Server: Ein Spieler trägt mit einem Auslöserblock „Feed the cats“ ein, ein anderer hakt es ab, und eine Anzeige zeigt allen die Liste. Der Server ist die Tutorial-API von c0de.at, die die Liste im Speicher hält und jede Nacht leert.
Funktionen: HTTP_POST, HTTP_PUT, HTTP_PATCH, HTTP_DELETE, HTTP_GET sowie TO_JSON und FROM_JSON aus c0de/strings
Was du brauchst
Die Mod c0de net in deinem Spiel, fünf Auslöserblöcke mit Knöpfen (einen für jede Funktion) und Schilder, um sie zu beschriften, eine Anzeigewand oder einen Laptop für die Liste, Variablenkarten title vom Typ STRING und id vom Typ INTEGER und eine nicht initialisierte Variablenkarte für das Ergebnis von show. Für die Übungen: einen weiteren Auslöserblock mit Knopf und eine nicht initialisierte Variablenkarte für das Programm todocleanup.
Die Idee
Ein REST-Dienst speichert Dinge – hier die Einträge einer Liste –, und jeder Eintrag hat seine eigene Adresse. Die HTTP-Methode sagt, was damit geschehen soll:
| Was | Methode | Endpunkt | Daten | Antwort |
|---|---|---|---|---|
| die Liste lesen | GET | /api/tutorial/todo | [{"id":1,"title":"…","done":false}, …] | |
| einen Eintrag anlegen | POST | /api/tutorial/todo | {"title":"…"} | 201 und der neue Eintrag mit seiner id |
| einen Eintrag ersetzen | PUT | /api/tutorial/todo/<id> | {"title":"…"} | der Eintrag |
| einen Teil davon ändern | PATCH | /api/tutorial/todo/<id> | {"done":true} | der Eintrag |
| einen Eintrag löschen | DELETE | /api/tutorial/todo/<id> | 204, keine Daten |
Die Daten sind JSON. JSON von Hand zu schreiben heißt Anführungszeichen in einem Text, und da passieren leicht Fehler; TO_JSON baut es stattdessen aus einer Struktur oder einer Variablen. Der Header Content-Type: application/json sagt dem Server, was er bekommt.
Die Liste ist für jeden Spieler in jeder Welt dieselbe, also sei nett: Sie fasst höchstens 100 Einträge mit Titeln bis zu 100 Zeichen, nimmt 60 Anfragen pro Minute von einem Computer an und wird um 00:00 UTC geleert. Die Anfragen kommen vom Computer des Spielers, der den Knopf drückt; jeder Spieler kann sie für seinen eigenen Computer abschalten.
Das Programm
PROGRAM todolist
NOOP
INCLUDE c0de/strings
INCLUDE c0de_net/http
NOOP
STRUCT todo
BEGIN
id INTEGER
title STRING
done BOOLEAN
END STRUCT
NOOP
STRUCT change
BEGIN
title STRING
END STRUCT
NOOP
FUNCTION connect
RESULT api STRUCT c0de_net/http/HTTP_CONNECTION
BEGIN
ASSIGN api.use_ssl TRUE ;
ASSIGN api.server "c0de.at" ;
ASSIGN api.base_endpoint "/api/tutorial/todo" ;
ASSIGN api.headers["Content-Type"] "application/json" ;
ASSIGN api.timeout 10 ;
END FUNCTION
NOOP
FUNCTION add
PARAMETER title STRING
RESULT id INTEGER
BEGIN
VARIABLE api STRUCT c0de_net/http/HTTP_CONNECTION
VARIABLE entry STRUCT change
VARIABLE data STRING
VARIABLE answer STRING
VARIABLE created STRUCT todo
CALL connect
RESULT api api
ASSIGN entry.title title ;
CALL c0de/strings/TO_JSON
PARAMETER value entry ;
RESULT result data
CALL c0de_net/http/HTTP_POST
PARAMETER connection api ;
PARAMETER data data ;
RESULT result answer
CALL c0de/strings/FROM_JSON
PARAMETER source answer ;
PARAMETER destination created ;
ASSIGN id created.id ;
END FUNCTION
NOOP
FUNCTION rename
PARAMETER id INTEGER
PARAMETER title STRING
RESULT answer STRING
BEGIN
VARIABLE api STRUCT c0de_net/http/HTTP_CONNECTION
VARIABLE entry STRUCT change
VARIABLE data STRING
CALL connect
RESULT api api
ASSIGN entry.title title ;
CALL c0de/strings/TO_JSON
PARAMETER value entry ;
RESULT result data
CALL c0de_net/http/HTTP_PUT
PARAMETER connection api ;
PARAMETER endpoint "/" ⊕ id ;
PARAMETER data data ;
RESULT result answer
END FUNCTION
NOOP
FUNCTION complete
PARAMETER id INTEGER
RESULT answer STRING
BEGIN
VARIABLE api STRUCT c0de_net/http/HTTP_CONNECTION
VARIABLE done BOOLEAN TRUE TAG(json: "done")
VARIABLE data STRING
CALL connect
RESULT api api
CALL c0de/strings/TO_JSON
PARAMETER value done ;
RESULT result data
CALL c0de_net/http/HTTP_PATCH
PARAMETER connection api ;
PARAMETER endpoint "/" ⊕ id ;
PARAMETER data data ;
RESULT result answer
END FUNCTION
NOOP
FUNCTION remove
PARAMETER id INTEGER
RESULT status INTEGER
BEGIN
VARIABLE api STRUCT c0de_net/http/HTTP_CONNECTION
CALL connect
RESULT api api
CALL c0de_net/http/HTTP_DELETE
PARAMETER connection api ;
PARAMETER endpoint "/" ⊕ id ;
RESULT status status
END FUNCTION
NOOP
FUNCTION show
RESULT count INTEGER
BEGIN
VARIABLE api STRUCT c0de_net/http/HTTP_CONNECTION
VARIABLE answer STRING
VARIABLE list ARRAY STRUCT todo
VARIABLE mark STRING
CALL connect
RESULT api api
CALL c0de_net/http/HTTP_GET
PARAMETER connection api ;
RESULT result answer
CALL c0de/strings/FROM_JSON
PARAMETER source answer ;
PARAMETER destination list ;
CALL CLS
EACH entry list
BEGIN
ASSIGN mark "[ ] " ;
IF entry.done ;
BEGIN
ASSIGN mark "[x] " ;
END IF
CALL PRINT
PARAMETER value mark ⊕ entry.id ⊕ " " ⊕ entry.title ;
END EACH
CALL LEN
PARAMETER value list ;
RESULT result count
END FUNCTIONAufbauen und starten
- Stelle für jede Funktion des Programms
todolisteinen Auslöserblock auf:add,rename,complete,removeundshow. Beschrifte sie mit Schildern. - Binde die Anzeigewand oder den Laptop an
todolist/show. add: Leg eine VariablenkartetitlemitFeed the catsin den Auslöserblock und drück seinen Knopf. Ein Ergebnis nimmt den Platz einer Parameterkarte ein, also brauchenadd,complete,renameundremovekeine nicht initialisierte Karte. Die Ergebniskarteidenthält die Nummer des neuen Eintrags, zum Beispiel 1. TragBuild a farmgenauso ein (2).complete: Leg eine Karteidmit 1 hinein. Das Ergebnisanswerkommt an ihrer Stelle heraus und ist die Antwort des Servers:{"id":1,"title":"Feed the cats","done":true}.rename: Kartenid2 undtitleBuild a big farm. Die Antwort ist{"id":2,"title":"Build a big farm","done":false}.remove: eine Karteid, die als Ergebnisstatuszurückkommt. Es ist 204: gelöscht, nichts zu antworten.showhat keinen Parameter, also leg eine nicht initialisierte Karte für sein Ergebniscounthinein. Es gibt die Liste aus, undcountenthält die Zahl der Einträge, 2:
[x] 1 Feed the cats
[ ] 2 Build a big farmAndere Spieler sehen dieselbe Liste – und die Nummern anderer Einträge, denn alle teilen sie.
So funktioniert es
- Eine Verbindung für alle.
connectliefert eine fertige HTTP_CONNECTION, so stehen der Server, der Basis-Endpunkt/api/tutorial/todound der Header nur einmal da. Jede Anfrage hängt ihren Endpunkt an die Basis an: nichts für die Liste,"/" ⊕ idfür einen Eintrag. - POST legt an.
addfüllt die Strukturchangeund lässt TO_JSON sie schreiben:{"title":"Feed the cats"}. Der Server antwortet mit 201 und dem neuen Eintrag, und FROM_JSON liest ihn increated, eintodomitid,titleunddone. - Zwei Strukturen. Der Server lehnt Schlüssel ab, die er nicht kennt, und er vergibt die
idjedes Eintrags selbst. Deshalb haben die Daten, die hinausgehen (change), nur einen Titel, und die Antwort, die hereinkommt (todo), alle drei Elemente. - PUT ersetzt, PATCH ändert. PUT sendet den ganzen Eintrag und setzt alles, was fehlt, auf den Standardwert: Ein umbenannter Eintrag ist nicht mehr erledigt. PATCH sendet nur, was sich ändert.
VARIABLE done BOOLEAN TRUE TAG(json: "done")ergibt mit TO_JSON genau{"done":true}: Ein Tag in einer VARIABLE-Zeile ist der Pfad, an den TO_JSON den Wert setzt. - DELETE antwortet mit einem Status. Es gibt keine Daten zu lesen, also liefert
removedenstatus, 204 („No Content“). - Falsche Anfragen sind Fehler. Eine
id, die es nicht gibt, ergibt 404, ein leerer Titel 400, eine volle Liste 409. Jeder davon löst HTTP_STATUS (Code 1000) aus, und der Prozess stürzt ab. Wenn das Netz ausfällt zeigt, wie du sie abfängst und den Grund liest, den der Server nennt.
Probier es selbst
- Schreib eine Funktion, die alle erledigten Einträge löscht und zurückgibt, wie viele sie gelöscht hat.
Lösung
PROGRAM todocleanup
NOOP
INCLUDE c0de/strings
INCLUDE c0de_net/http
NOOP
STRUCT todo
BEGIN
id INTEGER
title STRING
done BOOLEAN
END STRUCT
NOOP
FUNCTION cleanup
RESULT removed INTEGER
BEGIN
VARIABLE api STRUCT c0de_net/http/HTTP_CONNECTION
VARIABLE answer STRING
VARIABLE list ARRAY STRUCT todo
ASSIGN api.use_ssl TRUE ;
ASSIGN api.server "c0de.at" ;
ASSIGN api.base_endpoint "/api/tutorial/todo" ;
ASSIGN api.timeout 10 ;
CALL c0de_net/http/HTTP_GET
PARAMETER connection api ;
RESULT result answer
CALL c0de/strings/FROM_JSON
PARAMETER source answer ;
PARAMETER destination list ;
EACH entry list
BEGIN
IF entry.done ;
BEGIN
CALL c0de_net/http/HTTP_DELETE
PARAMETER connection api ;
PARAMETER endpoint "/" ⊕ entry.id ;
ASSIGN removed removed + 1 ;
END IF
END EACH
END FUNCTIONGET liest die ganze Liste, EACH geht sie durch, und jeder Eintrag mit done bekommt sein eigenes DELETE. Ohne RESULT-Zeile wirft der CALL alle Ergebnisse weg. Stelle den zusätzlichen Auslöserblock auf todocleanup / cleanup, leg eine nicht initialisierte Variablenkarte für das Ergebnis removed hinein und drück seinen Knopf. Nach den Schritten oben ist removed gleich 1.
- Hake den Eintrag 99 ab, den es nicht gibt. Was zeigt der Auslöserblock?
Lösung
Der Prozess stürzt mit dem Fehler 1000 ab, HTTP_STATUS, und der Meldung 404 Not Found. Alle Karten kommen unverändert aus dem Auslöserblock. Der Server sagt auch, warum, in seiner Antwort {"error":"no such entry"}; die erste Übung von Wenn das Netz ausfällt liest sie.