Skip to content

feat: write the API guides - #1644

Draft
jubianchi wants to merge 3 commits into
dev-null-sh:productionfrom
jubianchi:feat/api-docs-guides
Draft

jubianchi wants to merge 3 commits into
dev-null-sh:productionfrom
jubianchi:feat/api-docs-guides

Conversation

@jubianchi

@jubianchi jubianchi commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Depends on #1643, still open. Until it merges, this diff also shows its changes and #1642's; this pull request's own changes.

Summary

The API docs get the guides that tell what a reference can't: Authentication, Rate limits, Pagination and Errors. Third of five pull requests splitting #1533.

Changes

  1. Authentication. Public and signed requests, getting a key approved with PKCE, and signing a request, with a helper for the shell, Laravel and Node.js (ApiExamples::signing()) under tabs that keep the client picked.
  2. Rate limits and Errors read their budgets and code meanings from the limiters, routes and ApiErrorCode, so they change with them. On a phone, an error's meaning reads under its code instead of in a column past the edge. The limits move to where they are enforced: commits a minute to Commit, issues a day to CreateIssue, failed signatures a minute to SignedRequests.
  3. Pagination says which lists page differently. The Introduction now points to Pagination and Authentication.

A few sentences of Authentication mention the reference, which lands in #1646. The signing helpers sit under curl, Laravel and fetch tabs (the Node.js helper is what the fetch examples call), so the client picked here is the one the reference shows.

# Pull request Depends on
0 #1642 the console layout production
1 #1643 the API docs page and its Introduction 0
2 this one 1
3 #1645 the OpenAPI spec 2
4 #1646 the endpoint reference and search 3

Validation

Check Result
pest --parallel --coverage --exactly=100.0 (full suite) 6495 passed, 100.0%
pest --type-coverage --min=100 100.0%
pint --test, rector --dry-run, phpstan clean
TSX tests, tsc 1133 passed, clean
Errors at 390 each meaning under its code, no page overflow

ApiSigningGuideTest signs a read, a write without a body and a write with one through each helper exactly as the guide shows it, with a key made by ssh-keygen, and the API accepts them.

Visual evidence

Playwright (Chromium) against a local dev server on this branch, emulated viewports, Inertia SSR off. Each guide was captured at 1440×900, 1366×650 and 390×844, light and dark: layout shift (CLS) 0 on load, no horizontal overflow, no console error. Arrow keys on the signing tabs move focus and the selection together.

Authentication, 1440 light 390 dark Rate limits, 1440 light 1366 dark
Authentication, desktop, light Authentication, mobile, dark Rate limits, desktop, light Rate limits, laptop, dark
Pagination, 1440 dark Errors, 1440 light Focus on the signing tabs, 1440 dark
Pagination, desktop, dark Errors, desktop, light Keyboard focus on the Laravel signing tab, desktop, dark
Error codes, 1440 dark 390 light, each meaning under its code
Error codes table, desktop, dark Error codes table with each meaning under its code, mobile, light

Device verification

Emulation only (390×844, DPR 2, touch): no hardware or simulator.

Independent review

Fresh read-only reviewers, given the guidelines, the stack, the validation results and the captures. A first round on the previous heads found should-fix points (fixtures and options ahead of their PR, the Errors table hiding its meanings on a phone, the Guilds preview, captures from before production's guild fields), all fixed. Re-review on base 1aa85cf4, head 5362b047: CODE: PASS, VISUAL: PASS, no blocker or should-fix. Left as is: a few sentences of Authentication mention the reference that lands in #1646.

Limitations

  • An unsigned 429 has no code; the pings and commit search limits answer without one; ThrottleCommits answers a scheduled commit from the API with a 302 unless it sends Accept: application/json. The guides describe the API as it behaves; these are left for a separate PR.
  • Authentication describes today's sign-in (loopback or devnull://); the device flow PR (feat: sign in to the API from a terminal with a device code #585, still open) changes that.

The API docs page reuses the operations console's shell: the sidebar of
grouped pages, the header naming the current one, the mobile nav that
scrolls sideways, the theme switch and the way back to /dev/null.

ConsoleLayout now draws that shell from its props: the brand chip and
label, the nav landmark's own label, whether its links prefetch, and a
title that falls back to the console's name. OperationsLayout keeps
what only operations does (polling, refreshing, the remotes dock) and
passes its pages in, with Moderation as an item elsewhere and prefetch
off, as before. Nothing changes on screen: captures before and after
differ only in the pulsing live dot.

Two things only the API docs will use come with it, as part of the
shell: links that prefetch, which operations leaves off, and the way
back for a guest on a phone, since operations only has signed-in
admins.
/docs/api opens the API docs, readable by everyone, on the console
layout: the guides in the sidebar, the section named in the header,
and the way back to /dev/null. A section the docs don't have is the
not found page.

This first step brings the page and its Introduction: what the API is
for, its base URL and format, and a first request anyone can send. Its
code is highlighted on the server and shown in the site's own code
blocks. The other guides, the OpenAPI spec and the endpoint reference
follow in their own pull requests.

The docs are linked as API from the aside, after Apps, and from the
user menu where the aside is hidden.
The API docs get the guides that tell what a reference can't.
Authentication: public and signed requests, getting a key approved with
PKCE, and signing a request, with a helper for the shell, Laravel and
Node.js under tabs that keep the client picked. Rate limits and Errors
read their budgets and code meanings from the limiters, routes and
ApiErrorCode, so they change with them; on a phone, an error's meaning
reads under its code. Pagination says which lists
page differently. The Introduction now points to Pagination and
Authentication.

The limits the guide lists move to where they are enforced and read
from there: the commits a minute to Commit, the issues a day to
CreateIssue, the failed signatures a minute to SignedRequests. A test
signs a read, a write without a body and a write with one through each
helper exactly as the guide shows it, and the API accepts them.
@coderabbitai

coderabbitai Bot commented Nov 19, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant