2.4 Making your first request (and reading the response)

With a node running on loopback and the open bootstrap tenant from 2.3, let's write, read, and list some resources. We'll use curl.exe here; any HTTP client works. Part 5 adds authentication before this config goes anywhere near a network.

Write a file

curl.exe -X PUT http://127.0.0.1:3100/files/docs/hello.txt `
  -H "Content-Type: text/plain" --data "Hello, RS2"

You get 201 Created (or 200 if it already existed), an empty body, and an ETag header — a version stamp for the resource. The write streamed straight to storage; nothing was buffered in full.

Read it back

curl.exe -i http://127.0.0.1:3100/files/docs/hello.txt

The response carries the body, the Content-Type from the file's extension (text/plain), the ETag, and Last-Modified. Media types come from the extension, never sniffed — an unknown extension is served as application/octet-stream.

List a directory

A trailing slash means "list this container":

curl.exe http://127.0.0.1:3100/files/docs/

{ "path": "/docs/", "entries": [ { "name": "hello.txt", "dir": false } ], "total": 1 }

This application/vnd.rs2.dir+json listing shape is the same on every store (it's the store pattern, Part 3/4). Sub-containers appear with "dir": true; page large listings with $take/$skip.

Store a JSON record

The data service is a store too, so the verbs match — but it holds JSON:

curl.exe -X PUT http://127.0.0.1:3100/data/people/ada `
  -H "Content-Type: application/json" --data '{\"name\":\"Ada\",\"role\":\"pioneer\"}'

GET /data/people/ada returns the record with a content-hash ETag; GET /data/people/ lists the keys. (Windows PowerShell mangles inline JSON quotes in some shells — if the body looks wrong, build it with ConvertTo-Json or use a here-string; see Appendix and Part 9.)

Reading any response

Two things are worth noticing on every response:

X-Trace-Id — a unique id for the request, echoed as a header. It correlates the response to its log line (Part 10) — keep it when reporting a problem.
Errors are structured. A failure is never a bare string; it's application/problem+json with a machine-readable code. Try reading a missing file:

{ "type": "https://rs2.dev/errors#not_found", "title": "Not Found",
  "status": 404, "code": "not_found", "traceId": "…" }

You now have the full read/write/list loop. The last section of this part shows the CLI shortcuts for the developer workflow.

← Previous: 2.3 Minimal tenant config · Manual home · Next: 2.5 Health checks & confirming the node →