Reference · by task

Build an API

Routes with one typed input and output, the failures callers see, and the OpenAPI document written for you. Read them in this order. Each page links to the pages around it.

1. Route groups

   Every route belongs to a route group: a routes declaration with a name and a prefix:.

2. Paths and placeholders

   A placeholder in a path is typed where it appears, and reaches what the route runs by its name:

3. One input

   A route reads at most one input, named by input:.

4. Output and status

   output: names what the route answers with: an Output type, an object made to be sent to clients.

5. What a route runs

   run: calls one named action.

6. Declaring a failure

   A failure is a way an action or query can fail that its caller is expected to handle, such as a todo that doesn't exist.

7. Saying what can fail: fails

   A function or action lists the failures it can end with after fails, in its signature:

8. How failures reach the client

   Every failure reaches the client in one envelope: code, message, request_id, and the failure's client fields under details (Failures).

9. Idempotent writes

   A client that retries a write after a timeout can't tell whether the first try worked.

10. Time limits

    Every route has a deadline: 10 seconds, unless deadline: sets another, and never more than 60.

11. OpenAPI

    The compiler writes one OpenAPI 3.1 document per API into build/openapi/.

12. The public API record

    Each API has a committed, readable record of its routes, fields and failure codes: api/main.jadpo_record for main.