psmattas/Outpost
1
0
Fork 0
Code Issues Pull Requests Actions Releases 4 Wiki Activity

docs(architecture): vendor Outline's OpenAPI spec for reference

Browse Source 
Local copy at docs/reference/outline-openapi-spec3.yml (from
outline/openapi) so exact request/response shapes are checkable
without network access before adding new OutlineAPIClient methods —
already caught two real mismatches (documents.search's sort field
rejecting "relevance" as an explicit value, documents.search_titles
not working against this instance at all).
This commit is contained in:
Puranjay Savar Mattas
2026-08-14 01:42:41 +01:00
parent a0f3d591a7
commit b933b19d6e
2 changed files with 7582 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ARCHITECTURE.md
+1
View File
@@ -8,6 +8,7 @@ Deeper technical reference backing `CLAUDE.md`. Update this as decisions are mad
- **Auth**: `Authorization: Bearer <API_KEY>` header. Keys are created per-user under Settings → API Keys on the Outline instance. Store in Keychain, scope a dedicated key to this app rather than reusing a personal one. - **Auth**: `Authorization: Bearer <API_KEY>` header. Keys are created per-user under Settings → API Keys on the Outline instance. Store in Keychain, scope a dedicated key to this app rather than reusing a personal one.
- **Core endpoints to wrap first**: `documents.info`, `documents.list`, `documents.search`, `documents.create`, `documents.update`, `collections.list`, `collections.info`, `users.info`. - **Core endpoints to wrap first**: `documents.info`, `documents.list`, `documents.search`, `documents.create`, `documents.update`, `collections.list`, `collections.info`, `users.info`.
- Full reference: your instance's `/developers` page (same docs as getoutline.com/developers, versioned per Outline release — check against your self-hosted version, not just the public docs). - Full reference: your instance's `/developers` page (same docs as getoutline.com/developers, versioned per Outline release — check against your self-hosted version, not just the public docs).
- **Full OpenAPI spec, vendored**: [`docs/reference/outline-openapi-spec3.yml`](reference/outline-openapi-spec3.yml) — pulled from [`outline/openapi`](https://github.com/outline/openapi). Check this before adding any new `OutlineAPIClient` method — read the exact request/response shape here rather than guessing from prose docs. It's already caught real mismatches twice: `documents.search`'s `sort` field rejects `"relevance"` as an explicit value even though the field is documented as accepting it (server only treats it as the implicit default when omitted), and `documents.search_titles` doesn't work against this self-hosted instance at all despite being in the spec (see `DocumentTitleSearchViewModel`'s doc comment — likely server version drift, matching the risk already called out below). Re-pull from the source repo periodically since it can drift from what's actually deployed.
## 2. Realtime collaboration transport ## 2. Realtime collaboration transport
docs/reference/outline-openapi-spec3.yml
+7581
View File
File diff suppressed because it is too large Load Diff