lino-rest-api (JavaScript)

A REST API framework and client that speak Links Notation instead of JSON.

Everything the HTTP standards expect of a REST service — content negotiation, conditional requests, problem details, collection pagination, automatic HEAD/OPTIONS/405, CORS, a service description and an OpenAPI document — is provided out of the box, with LINO as the default wire format and JSON as a fallback.

The wire protocol is defined in docs/spec/README.md; tests/conformance.test.js is its executable form.

Installation

npm install lino-rest-api
# or
bun add lino-rest-api

Requires Node 20+, Bun or Deno — the client is built on the platform fetch, so it also runs in browsers.

Quick start

import { createLinoApp, MemoryStore } from "lino-rest-api";

const app = createLinoApp({ title: "Tasks API", version: "1.0.0", cors: true });

const tasks = new MemoryStore();
tasks.create({ title: "Write the specification", done: true });

// Registers list, create, get, replace, merge and delete, with entity tags,
// pagination, problem details, automatic HEAD/OPTIONS and 405.
app.resource("/tasks", tasks, { name: "task" });

app.get("/health", () => ({ status: "ok" }));

app.listen(3000, () => console.log("Listening on http://localhost:3000"));

curl -H 'Accept: text/lino' http://localhost:3000/tasks/1

(
  title "Write the specification"
  done true
  id 1
)

A full tour — negotiation, pagination, conditional requests, problem details — is in examples/basic_usage.js:

npm run example

The client

import { createLinoClient } from "lino-rest-api";

const client = createLinoClient("http://localhost:3000");

const created = await client.post("/tasks", { title: "Ship it", done: false });
// → { status: 201, location: "/tasks/2", etag: '"…"', data: { … } }

const page = await client.list("/tasks", {
  done: false,
  sort: "-id",
  limit: 10,
});
// → { items: [ … ], page: { limit: 10, offset: 0, total: 1, count: 1 } }

const fresh = await client.get("/tasks/2", { ifNoneMatch: created.etag });
// → { status: 304, data: undefined }

try {
  await client.get("/tasks/999");
} catch (error) {
  error.status; // 404
  error.problem; // { type, title, status, detail, instance }
}

Requests are sent as text/lino and Accept: text/lino, application/json;q=0.5 by default; 4xx and 5xx responses become a LinoClientError carrying the decoded problem details.

Representations

| Media type | Shape | | ------------------- | ---------------------------------------------------------- | | text/lino | Readable, indented Links Notation. The default. | | text/lino-line | The same value on a single line: (o: (a 1)). | | text/lino-compact | Type-tagged base64, preserving object identity and cycles. | | application/json | Fallback for clients that cannot speak LINO. |

Errors use application/problem+lino (or application/problem+json), carrying RFC 9457 problem details.

The response representation is chosen from Accept, including quality values; every response carries Vary: Accept, an unsatisfiable Accept is a 406, and an undecodable Content-Type is a 415.

Resources

app.resource(path, store, options) turns any store into a full collection:

| Request | Behaviour | | ------------------- | ---------------------------------------------------- | | GET /tasks | Envelope {items, page} with Link pagination | | POST /tasks | 201 with Location and the created representation | | GET /tasks/:id | The representation, with a strong ETag | | PUT /tasks/:id | Replace (optionally upsert) | | PATCH /tasks/:id | Merge | | DELETE /tasks/:id | 204 |

Collection queries support limit, offset, sort=-priority,title, fields=id,title and arbitrary field filters (?done=false&tag=a&tag=b).

A store is any object with list, get, create, update, patch and remove; MemoryStore is the built-in implementation, and it may be replaced with anything that fulfils the same contract (including async database access).

Options: name (used in problem details), operations (subset of ["list", "create", "get", "update", "patch", "remove"]), upsert, requirePrecondition.

Conditional requests

Every representation carries a strong ETag: the SHA-256 of the encoded body, so the tag is per representation — the LINO and JSON forms of the same value have different tags, which is why Vary: Accept is always present.

• If-None-Match on a safe method → 304 Not Modified
• If-Match that does not match → 412 Precondition Failed
• no If-Match where one is required → 428 Precondition Required

Describing the service

| Path | Document | | --------------------------- | --------------------------------------------------------- | | /.well-known/lino-api | Service description: routes, methods, media types, info | | /.well-known/openapi.json | OpenAPI 3.1, every media type declared, problem responses |

app.describe() and app.openapi() return the same documents in process.

Handlers

A handler receives the Express request and returns a value, which is encoded as the negotiated representation:

import { created, noContent, status, LinoHttpError } from "lino-rest-api";

app.post("/echo", (req) => ({ echoed: req.body }));
app.post("/tasks", (req) => created({ id: 7 }, "/tasks/7"));
app.delete("/tasks/:id", () => noContent());
app.get("/teapot", () => status(418, { short: true, stout: true }));

app.get("/guarded", () => {
  throw new LinoHttpError(403, "Not for you", { title: "Forbidden" });
});

Returning undefined sends 204. Any thrown value becomes problem details; LinoHttpError controls the status, title, headers and extension members.

Collection queries are parsed on demand with req.collectionQuery().

API reference

Generated with JSDoc:

npm run docs

Key exports: createLinoApp, LinoApp, createLinoClient, LinoClient, LinoClientError, MemoryStore, registerResource, LinoHttpError, ok, created, accepted, noContent, status, encode, decode, encodeFor, decodeFrom, encodeSingleLine, encodeCompactNotation, linoMiddleware, linoBodyParser, linoNegotiation, linoErrorHandler, linoCors, computeETag, evaluatePreconditions, parseCollectionQuery, applyCollectionQuery, collectionEnvelope, paginationLinkHeader, serviceDescription, openApiDocument.

Tests

npm test          # node --test tests/*.test.js
bun test          # the same suites under Bun

License

Unlicense