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:
| What | Method | Endpoint | Data | Answer |
|---|---|---|---|---|
| read the list | GET | /api/tutorial/todo | [{"id":1,"title":"…","done":false}, …] | |
| add an entry | POST | /api/tutorial/todo | {"title":"…"} | 201 and the new entry with its id |
| replace an entry | PUT | /api/tutorial/todo/<id> | {"title":"…"} | the entry |
| change part of an entry | PATCH | /api/tutorial/todo/<id> | {"done":true} | the entry |
| delete an entry | DELETE | /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
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 FUNCTIONBuilding and running it
- Set up one trigger block per function of the program
todolist:add,rename,complete,removeandshow. Label them with signs. - Bind the display wall or the laptop to
todolist/show. add: put a variable itemtitlewithFeed the catsinto the trigger block and press its button. A result takes the place of a parameter item, soadd,complete,renameandremoveneed no uninitialized item. The result itemidholds the number of the new entry, for example 1. AddBuild a farmthe same way (2).complete: put an itemidwith 1 in it. The resultanswercomes out in its place and is what the server answers:{"id":1,"title":"Feed the cats","done":true}.rename: itemsid2 andtitleBuild a big farm. The answer is{"id":2,"title":"Build a big farm","done":false}.remove: an itemid, which comes back as the resultstatus. It is 204: deleted, nothing to answer.showhas no parameter, so put an uninitialized item in for its resultcount. It prints the list andcountholds the number of entries, 2:
[x] 1 Feed the cats
[ ] 2 Build a big farmOther players see the same list – and the numbers of other entries, because everybody shares it.
How it works
- One connection for all.
connectreturns a ready HTTP_CONNECTION, so the server, the base endpoint/api/tutorial/todoand the header are written only once. Every request adds its endpoint behind the base: nothing for the list,"/" ⊕ idfor one entry. - POST creates.
addfills the structchangeand lets TO_JSON write it:{"title":"Feed the cats"}. The server answers 201 with the new entry, and FROM_JSON reads it intocreated, atodowithid,titleanddone. - Two structs. The server refuses keys it doesn't know, and it gives every entry its
iditself. 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
removereturnsstatus, 204 ("No Content"). - Mistakes are errors. An
idthat 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
- Write a function that deletes all completed entries and returns how many it deleted.
Solution
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 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.
- 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.