turlte API

New turtles start at a random spot. A GET or POST move turns the turtle towards where it goes. Colours are a hue from 0 to 255:

Een nieuwe schildpad begint op een willekeurige plek. Bij een GET of POST draait de schildpad in de richting waarin hij beweegt. Kleuren zijn een hue van 0 tot 255:

Call it again with another position and a line is drawn between the two points. x (0–1000) and y (0–600) are both required.

Roep hem opnieuw aan met een andere positie en er komt een lijn tussen de twee punten. x (0–1000) en y (0–600) zijn allebei verplicht.

curl

curl "http://localhost:3000/api/1234-5678/?x=200&y=300"

JavaScript

const res = await fetch('http://localhost:3000/api/1234-5678/?x=200&y=300');
console.log(await res.json());

ResponseAntwoord

{ "ok": true, "state": { "id": "a3f8c2d1e4b9", "x": 200, "y": 300, … } }

http://localhost:3000/api/1234-5678/?x=200&y=300

Send any combination, but at least one field. Only name renames without moving.

Stuur elke combinatie, maar minstens één veld. Alleen name geeft een nieuwe naam zonder te bewegen.

JavaScript

const res = await fetch('http://localhost:3000/api/1234-5678/', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ x: 500, y: 300, hue: 170, width: 4, name: 'Alice' }),
});
console.log(await res.json());

curl -X POST http://localhost:3000/api/1234-5678/ \
  -H "Content-Type: application/json" \
  -d '{"x": 500, "y": 300, "hue": 170, "width": 4, "name": "Alice"}'

The server answers hello on connect and ack after every message, both with your turtle's state. A message may also carry name, hue, width, x and y; those are applied before the command. Heading: 0° is up, 90° right, clockwise. Your turtle wears a 👑 once it has used a WebSocket.

De server antwoordt hello bij het verbinden en ack na elk bericht, allebei met de state van je schildpad. Een bericht mag ook name, hue, width, x en y bevatten; die worden eerst toegepast. Richting: 0° is omhoog, 90° rechts, met de klok mee. Je schildpad krijgt een 👑 zodra hij een WebSocket heeft gebruikt.

Errors come back as {"type": "error", "message": …} and the connection stays open. Messages are JSON objects of at most 4 KB.

Fouten komen terug als {"type": "error", "message": …} en de verbinding blijft open. Berichten zijn JSON-objecten van hooguit 4 KB.

const ws = new WebSocket('ws://localhost:3000/ws/1234-5678');
ws.onmessage = (e) => console.log(JSON.parse(e.data));
ws.onopen = () => {
  for (let i = 0; i < 4; i++) {
    ws.send(JSON.stringify({ cmd: 'move', steps: 100 }));
    ws.send(JSON.stringify({ cmd: 'turn', degrees: 90 }));
  }
  ws.send(JSON.stringify({ cmd: 'coinspray' }));
};

All active turtles. Filter with ?id=a3f8c2d1e4b9,bb12ef34ab56 or ?tier=post,ws. A turtle without activity for 5 minutes disappears (an open WebSocket keeps it).

Alle actieve schildpadden. Filter met ?id=a3f8c2d1e4b9,bb12ef34ab56 of ?tier=post,ws. Een schildpad die 5 minuten niets doet verdwijnt (een open WebSocket houdt hem vast).

{ "ok": true, "turtles": [ { "id": "a3f8c2d1e4b9", "name": "Alice", "x": 500, "y": 300, … } ] }

This session's timeline: the latest trail segments and turtle snapshots (up to 10,000 each) with their time range. Large; refreshed at most every 5 seconds.

De tijdlijn van deze sessie: de laatste segments (lijnstukken) en snapshots van schildpadden (elk hooguit 10.000) met hun tijdrange. Groot; hooguit elke 5 seconden ververst.

{ "segments":  [ { "turtle": "a3f8c2d1e4b9", "x0": 200, "y0": 300, "x1": 350, "y1": 420, "hue": 85, "width": 3, "created_at": 1712345678000 } ],
  "snapshots": [ { "turtle": "a3f8c2d1e4b9", "name": "Alice", "x": 350, "y": 420, … } ],
  "range": { "min": 1712345000000, "max": 1712345999000 } }

A WebSocket closes on messages over 4 KB, on more than 4 connections at once, and with code 1000 when the session ends.

Een WebSocket sluit bij berichten groter dan 4 KB, bij meer dan 4 verbindingen tegelijk, en met code 1000 als de sessie afloopt.