Reference
Reference
Services and requests
Every setting of a service, the endpoint grammar, call options, a read's members, HttpError, caching, retries, middleware, fakes and the N codes.
Lookup tables for api, http and resource. Fetching data teaches them in order.
Service settings
What api Backend(…) { … } takes, in its parentheses or at the top of its block, before the endpoints; a group (api Backend.users { … }) takes none of them.
| Setting | Values | Unset |
|---|---|---|
|
|
The address every path is below: |
— |
|
|
A duration, after which a call fails |
|
|
|
A count ( |
no retries |
|
|
|
what the server's headers allow |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
A referrer policy: |
the page's |
|
|
The steps every request passes through, in order (Middleware) |
none |
|
|
|
— |
|
|
|
— |
|
|
|
— |
Endpoint grammar
One line an endpoint: verb name(parameters) at "path" -> result, then its modifiers.
| Part | Written | Means |
|---|---|---|
| Verb |
|
The HTTP method |
| Path |
|
Required; below |
| Path parameter |
|
Filled in, URL-encoded. |
| Body |
|
The request body, as JSON |
| File |
|
The call is sent as a form; |
| Query parameter |
any other parameter; |
The query string under its own name, or the one written; |
| Header parameter |
|
Sent as that header |
| Cookie parameter |
|
Set as that cookie |
| Default |
|
Sent when the call leaves it out |
| Optional |
|
May be left out; a parameter with neither must be given ( |
| Result |
|
A |
| Result with an error enum |
|
A |
| No value |
|
Nothing (a |
|
|
after the result |
Safe to send twice: one |
|
|
on a write |
Reads of the same group a success makes stale; arguments are the write's parameters ( |
|
|
on a read | Next page: the parameter, one more; ends at an empty page |
|
|
on a read |
Next page: the cursor |
|
|
on a read |
Next page: the |
|
|
on a |
One JSON value a line, each held to the item type |
|
|
after the result | How a success's body is read; JSON unset |
|
|
as |
How a failure's body is read |
|
|
|
This endpoint's cache policy |
The cases of an error enum, what an endpoint's -> T ! E names (N12).
| Case | Written | Holds |
|---|---|---|
| A status |
|
That status's body, held to its type |
| A class |
|
Every status of the class no other case names |
| The rest |
|
Required, once: every other failure |
Call options
Named arguments a call takes beside the endpoint's parameters; http.get(url, …) takes the same.
| Option | Values | Where |
|---|---|---|
|
|
What is sent, as JSON (a |
|
|
|
A map: |
any call |
|
|
A duration | any call |
|
|
As the service setting ( |
any call |
|
|
|
any call |
|
|
|
any call |
|
|
|
a |
|
|
|
a |
A read's cases and members
What resource name = … is. A match over it takes each case.
| Case | When |
|---|---|
|
|
Nothing to show: a first load, or a request whose address changed |
|
|
The first load failed; |
|
|
Something to show; |
| Member | What it is |
|---|---|
|
|
The value while |
|
|
Which case it is in |
|
|
|
|
|
The first load's failure, or the last refresh's, else |
|
|
Any request of it running, the first load included |
|
|
Asks again: a refresh when a value is shown |
|
|
Drops what the cache holds for it, and asks again |
|
|
Aborts the request that is running |
|
|
A paged read: every item loaded so far, in order |
|
|
A paged read: whether there is a next page |
|
|
A paged read: the next page, as a refresh; nothing while a request runs |
A call's members
What an endpoint and an action carry, beside being called.
| Member | Of | What it is |
|---|---|---|
|
|
an endpoint | Drops its cache; every read of it on the page asks again. With arguments, one call's |
|
|
a read |
Changes what every read of it shows, at once; returns what takes it back ( |
|
|
an endpoint | Asks now, into the cache |
|
|
an endpoint | The address a call would ask |
|
|
an endpoint | The key its cache holds a call's answer under |
|
|
an endpoint with a |
The upload's progress, 0 to 1 |
|
|
an action |
|
|
|
an action that may fail |
Its last outcome, |
HttpError
What goes wrong between the page and the server. Every case has .message.
| Case | When |
Its |
|---|---|---|
|
|
The request reached no server: no network, a server down, a CORS refusal; |
the browser's words, or says so |
|
|
No answer within |
says so |
|
|
The scope left, the request changed, |
says so |
|
|
Anything else that stopped it: a middleware that threw |
|
|
|
The answer is not the declared type, or not JSON |
names the address and the place, |
|
|
An error status; |
the body's |
Problem, RFC 9457's account of a failure; a project extends it like any record, type ValidationProblem = Problem { errors: [FieldError] }.
| Field | Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Caching
A GET is kept as a private HTTP cache keeps it (RFC 9111), unless a cache: policy overrides the server.
| Server says | What is kept |
|---|---|
| No caching headers | Nothing |
|
|
Fresh for |
|
|
Fresh until then, when there is no |
|
|
Served stale for |
|
|
Kept, and asked again before every use |
|
|
Nothing |
|
|
Asked again with |
|
|
Kept apart by those request headers; |
| — | Kept apart by the credentials a request carries; at most 256 answers, the one read least recently dropped first |
| Policy | Means |
|---|---|
|
|
Fresh for |
|
|
Served at once; once older than |
|
|
The first answer, for good |
|
|
Nothing kept; every call asks |
Two readers of one address make one request, cached or not; each keeps its own abort.
Retries
What retry: does.
| Rule | |
|---|---|
| Methods retried |
|
|
Failures retried, unset |
|
|
|
|
| Never retried | A cancelled call |
| Wait |
|
|
|
The server's wait, in seconds or as a date, wins |
Middleware
A step is handed the request and the rest of the chain, next, and returns a result: .ok(json) or .err(httpError).
| Step | What it does |
|---|---|
|
|
|
|
|
One header, read as the request passes |
|
|
On a |
|
|
A fresh |
|
|
Each request and how it ended, in the console |
|
|
A step of the project's own; one that throws fails the call |
|
|
Type |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Fakes
fake Name for Backend.group { endpoint(params) { .ok(…) } }, as N06 holds it.
| Rule | |
|---|---|
| Endpoints | Each one it answers is one the group has, answered once |
| Parameters | Each name it binds is one of that endpoint's; one the call left out is its default |
| Answers |
|
|
|
Every endpoint it does not answer is answered with the spec's example of a success |
|
A test's |
Each names a fake; no two answer one endpoint |
| A call no fake answers | Fails the test, naming the endpoint |
|
A write's |
Asks its reads again, as it does live |
|
Pages · |
A paged endpoint is answered a page at a time; a streamed one with the whole list |
|
|
Names an endpoint the group has |
| Builds |
Leave fakes out; |
The codes
| Code | What it means |
|---|---|
|
A path's |
|
|
A |
|
|
|
|
| A call's result awaited on its own, so a failure is never heard | |
|
An |
|
| A fake that does not match its group's contract | |
|
A service's |
|
|
A 6.x form: |
|
|
|
|
|
|
|
|
An error enum without one |
|
|
A |
|
|
An async result used before it is awaited, or |
|
|
A |