Endpoint doc design
A repeatable pattern for documenting API endpoints that developers actually want to read.
Structure
Every endpoint page follows a strict top-down order: method badge, path, one-line summary, authentication note, request table, response table, and a curl example. Consistency is the feature — readers learn the layout once and scan forever.
Method badge
Lead with a colored pill: green for GET, violet for POST, amber for PATCH, red for DELETE. The badge sits inline with the path so the verb and route are read as one unit.
Request table
Four columns: parameter, type, required, description. Use a thin border between rows, no zebra striping. Mark optional params with a muted “No” and default values in the description cell.
| Parameter | Type | Required | Description |
|---|---|---|---|
| key | string | Yes | License key to validate |
| hwid | string | No | Hardware fingerprint (defaults to session) |
Response table
Same four-column layout. Show the happy-path response shape first, then list common error codes in a separate row group with a subtle red tint.
Curl example
A single copy-pasteable block. Use a dark code surface with violet accents for strings. Include the full command with headers so the reader never leaves the page to test.
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"key":"NIMBUS-XXXX-XXXX-XXXX","hwid":"abc123"}'