Diese Seite auf Deutsch

Talking to a REST service ​

A to-do list for your team that isn't stored in the world but on a server: one player adds "Feed the cats" with a trigger block, another completes it, and a display shows the list to everyone. The server is the tutorial API of c0de.at, which keeps the list in memory and empties it every night.

Functions: HTTP_POST, HTTP_PUT, HTTP_PATCH, HTTP_DELETE, HTTP_GET, and TO_JSON and FROM_JSON of c0de/strings

What you need

The mod c0de net in your game, five trigger blocks with buttons (one for each function) and signs to label them, a display wall or a laptop for the list, variable items title of type STRING and id of type INTEGER, and an uninitialized variable item for the result of show. For the exercises: one more trigger block with a button and an uninitialized variable item for the program todocleanup.

The idea ​

A REST service stores things – here, entries of a list – and every entry has its own address. The HTTP method says what to do with it:

WhatMethodEndpointDataAnswer
read the listGET/api/tutorial/todo[{"id":1,"title":"…","done":false}, …]
add an entryPOST/api/tutorial/todo{"title":"…"}201 and the new entry with its id
replace an entryPUT/api/tutorial/todo/<id>{"title":"…"}the entry
change part of an entryPATCH/api/tutorial/todo/<id>{"done":true}the entry
delete an entryDELETE/api/tutorial/todo/<id>204, no data

The data is JSON. Writing JSON by hand means quotes inside a text, which is easy to get wrong; TO_JSON makes it from a struct or a variable instead. The header Content-Type: application/json tells the server what it gets.

The list is the same for every player in every world, so be nice: it holds at most 100 entries with titles of up to 100 characters, takes 60 requests a minute from one computer, and is emptied at 00:00 UTC. The requests come from the computer of the player who presses the button; every player can switch them off for their own computer.

The program ​

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

Building and running it ​

  1. Set up one trigger block per function of the program todolist: add, rename, complete, remove and show. Label them with signs.
  2. Bind the display wall or the laptop to todolist / show.
  3. add: put a variable item title with Feed the cats into the trigger block and press its button. A result takes the place of a parameter item, so add, complete, rename and remove need no uninitialized item. The result item id holds the number of the new entry, for example 1. Add Build a farm the same way (2).
  4. complete: put an item id with 1 in it. The result answer comes out in its place and is what the server answers: {"id":1,"title":"Feed the cats","done":true}.
  5. rename: items id 2 and title Build a big farm. The answer is {"id":2,"title":"Build a big farm","done":false}.
  6. remove: an item id, which comes back as the result status. It is 204: deleted, nothing to answer.
  7. show has no parameter, so put an uninitialized item in for its result count. It prints the list and count holds the number of entries, 2:
[x] 1 Feed the cats
[ ] 2 Build a big farm

Other players see the same list – and the numbers of other entries, because everybody shares it.

How it works ​

  • One connection for all. connect returns a ready HTTP_CONNECTION, so the server, the base endpoint /api/tutorial/todo and the header are written only once. Every request adds its endpoint behind the base: nothing for the list, "/" ⊕ id for one entry.
  • POST creates. add fills the struct change and lets TO_JSON write it: {"title":"Feed the cats"}. The server answers 201 with the new entry, and FROM_JSON reads it into created, a todo with id, title and done.
  • Two structs. The server refuses keys it doesn't know, and it gives every entry its id itself. So the data that goes out (change) has only a title, and the answer that comes in (todo) has all three elements.
  • PUT replaces, PATCH changes. PUT sends the whole entry and sets everything that's missing to its default: a renamed entry is not done any more. PATCH sends only what changes. VARIABLE done BOOLEAN TRUE TAG(json: "done") with TO_JSON gives exactly {"done":true}: a tag on a VARIABLE line is the path where TO_JSON puts the value.
  • DELETE answers with a status. There is no data to read, so remove returns status, 204 ("No Content").
  • Mistakes are errors. An id that doesn't exist answers 404, an empty title 400, a full list 409. Each of them raises HTTP_STATUS (code 1000), and the process crashes. When the network fails shows how to catch them and read the reason the server gives.

Try it yourself ​

  1. Write a function that deletes all completed entries and returns how many it deleted.
Solution
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 reads the whole list, EACH goes through it, and every entry with done gets its own DELETE. Without a RESULT line, the CALL throws all results away. Set the extra trigger block to todocleanup / cleanup, put in an uninitialized variable item for the result removed and press its button. After the steps above, removed is 1.

  1. Complete the entry 99, which doesn't exist. What does the trigger block show?
Solution

The process crashes with error 1000, HTTP_STATUS, and the message 404 Not Found. All items come out of the trigger block unchanged. The server also says why, in its answer {"error":"no such entry"}; the first exercise of When the network fails reads it.

Read more ​