This page in English

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:

WasMethodeEndpunktDatenAntwort
die Liste lesenGET/api/tutorial/todo[{"id":1,"title":"…","done":false}, …]
einen Eintrag anlegenPOST/api/tutorial/todo{"title":"…"}201 und der neue Eintrag mit seiner id
einen Eintrag ersetzenPUT/api/tutorial/todo/<id>{"title":"…"}der Eintrag
einen Teil davon ändernPATCH/api/tutorial/todo/<id>{"done":true}der Eintrag
einen Eintrag löschenDELETE/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 ​

c0de
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 FUNCTION

Aufbauen und starten ​

  1. Stelle für jede Funktion des Programms todolist einen Auslöserblock auf: add, rename, complete, remove und show. Beschrifte sie mit Schildern.
  2. Binde die Anzeigewand oder den Laptop an todolist / show.
  3. add: Leg eine Variablenkarte title mit Feed the cats in den Auslöserblock und drück seinen Knopf. Ein Ergebnis nimmt den Platz einer Parameterkarte ein, also brauchen add, complete, rename und remove keine nicht initialisierte Karte. Die Ergebniskarte id enthält die Nummer des neuen Eintrags, zum Beispiel 1. Trag Build a farm genauso ein (2).
  4. complete: Leg eine Karte id mit 1 hinein. Das Ergebnis answer kommt an ihrer Stelle heraus und ist die Antwort des Servers: {"id":1,"title":"Feed the cats","done":true}.
  5. rename: Karten id 2 und title Build a big farm. Die Antwort ist {"id":2,"title":"Build a big farm","done":false}.
  6. remove: eine Karte id, die als Ergebnis status zurückkommt. Es ist 204: gelöscht, nichts zu antworten.
  7. show hat keinen Parameter, also leg eine nicht initialisierte Karte für sein Ergebnis count hinein. Es gibt die Liste aus, und count enthält die Zahl der Einträge, 2:
[x] 1 Feed the cats
[ ] 2 Build a big farm

Andere Spieler sehen dieselbe Liste – und die Nummern anderer Einträge, denn alle teilen sie.

So funktioniert es ​

  • Eine Verbindung für alle. connect liefert eine fertige HTTP_CONNECTION, so stehen der Server, der Basis-Endpunkt /api/tutorial/todo und der Header nur einmal da. Jede Anfrage hängt ihren Endpunkt an die Basis an: nichts für die Liste, "/" ⊕ id für einen Eintrag.
  • POST legt an. add füllt die Struktur change und lässt TO_JSON sie schreiben: {"title":"Feed the cats"}. Der Server antwortet mit 201 und dem neuen Eintrag, und FROM_JSON liest ihn in created, ein todo mit id, title und done.
  • Zwei Strukturen. Der Server lehnt Schlüssel ab, die er nicht kennt, und er vergibt die id jedes 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 remove den status, 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 ​

  1. Schreib eine Funktion, die alle erledigten Einträge löscht und zurückgibt, wie viele sie gelöscht hat.
Lösung
c0de
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 FUNCTION

GET 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.

  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.

Mehr dazu ​