# Building on the API An application on a federated swarm reads what counts at a node and writes as a party. This guide says how, through the client or with code of its own. The formats are the design's ([`federation.md`](../../federation.md), Events, The policy, What counts). ## Reading `GET /events/counts` is what counts, as the node reads it now: the values at places (`values`), the current version and its rules, each party's keys and nodes, the members ([`writing-and-reading.md`](writing-and-reading.md), Reading). There is no stream of what counts: read it again when the store's heads change (`heads` in `GET /events`). What a node answers is its word: it may be behind, and an application that must not take it on trust reads the events themselves (`GET /events/{id}`) and checks their signatures, or asks nodes of several parties. ## Writing through the client The simplest is the party's client, a command per write: ```sh continuum-party --node http://tv:secret@localhost:3000 --key laptop.key \ --record tv.record write home/tv/hosts/laptop '{"ip6": "42:0:a46e::1"}' ``` It signs on the heads the node shows, records what it signed, and puts it; `again` signs anew what a move to a checkpoint refused ([`writing-and-reading.md`](writing-and-reading.md), After a move). ## Writing with code of its own An event is the JCS encoding (RFC 8785) of an object, its member names sorted as JCS sorts them: ```json { "deps": [""], "key": "ssh-ed25519 AAAA…", "party": "tv", "sig": "", "write": { "path": "home/tv/hosts/laptop", "value": {"ip6": "42:0:a46e::1"} } } ``` * `deps`: the heads it read (`heads` in `GET /events`), each as 64 lower-case hex digits, ascending, one at least. * `key`: the key it signs with, its type (`ssh-ed25519` or `ecdsa-sha2-nistp256`), a space, the base64 of its blob, no comment; one of the party's keys. * `sig`: an SSH signature (`ssh-keygen -Y sign`, namespace `continuum-federation`, hashed with `sha512`) over the JCS bytes of the object without `sig`: the SSHSIG blob, its reserved field empty, in base64, unarmored. Of an ECDSA key, its `s` low, at most half the curve's order: `ssh-keygen` makes a high one half the time, which no node takes; sign again, or put the order less `s` in its place. * The value is any JSON with integers only, from −2⁵³ to 2⁵³; the event up to 256 KiB. Put its bytes as they are: ```sh curl -u tv:secret -X POST -H 'Content-Type: application/json' \ --data-binary @event.json localhost:3000/events # {"event":"taken","id":"0c7e…"} ``` Its ID is the SHA-256 of its bytes. A node takes no event that isn't byte for byte as the federation spells it; the vectors (`federation::vectors`) give events and their IDs to check code against. Keep what it signed: once the store moves to a checkpoint, a write signed on heads from before is refused (`it isn't above the checkpoint's heads`), and is to be signed again on the heads a node shows then. ## When a write counts At the node it was put through, at once where it is `taken` and the latest its party signed at that place: `GET /events/counts` shows it. At another node, once that node holds it (`GET /events/{id}` answers `200` there), as both read the same from the same events. ## One writer at a place Two writes of one party at one place, neither in the other's history, leave the one with the lower ID, whichever came last. Write each place from one client, on heads read just before; where two did, write again, after both. ## Keeping a namespace in step To have a party's namespace hold what an application keeps elsewhere: read `values`, write each place whose value differs, and `null` at each place of the namespace that the application holds no value for any more. Write nothing where a place holds the value already: a write is an event every node keeps until a checkpoint leaves it out. ## Not through the store API A node of a federated swarm refuses writes through the store API (`/store`): the document takes events and each node's own protocol data only.