[PR #146] [MERGED] docs: add API.md with API discoverability guide #146

New issue

Closed

opened 2026-09-01 07:34:18 +02:00 by zaph0d · 0 comments

zaph0d commented

2026-09-01 07:34:18 +02:00

Owner

📋 Pull Request Information

Original PR: https://github.com/niels-emmer/myace/pull/146
Author: @niels-emmer
Created: 8/31/2026
Status: ✅ Merged
Merged: 8/31/2026
Merged by: @niels-emmer

Base: main ← Head: docs/api-discoverability

📝 Commits (2)

78fa907 docs: add API.md with API discoverability guide
edbace7 Merge branch 'main' into docs/api-discoverability

📊 Changes

3 files changed (+148 additions, -0 deletions)

View changed files

➕ API.md (+143 -0)
📝 README.md (+1 -0)
📝 docs/README.md (+4 -0)

📄 Description

Summary

Adds API.md at the repo root documenting the MyACE HTTP API, following the api-discoverability-for-agents skill's discover → document → write-back loop.

What was found

No API.md, OpenAPI spec files, Postman collections, or .http files existed in the repo.
The backend (FastAPI) already serves a complete OpenAPI spec at /openapi.json — generated for free, served even in production (only the Swagger UI is disabled via docs_url=None; openapi_url stays at its default). Verified offline: 61 paths, every route covered.
Two discoverability gaps: (1) nothing in the repo pointed agents at the spec; (2) the spec declares no security schemes (auth is a custom Depends(get_current_user) dependency), so an agent reading only the spec cannot determine how to authenticate.

What changed

API.md (new) — orientation layer on top of the live spec: base URLs, spec endpoints, the two auth mechanisms (flagged as the authoritative auth reference), route-group table, and verified curl examples (register, login, token creation, list collections, compile, demo compile). All request/response shapes pulled from the actual generated schemas.
README.md / docs/README.md — linked API.md from the docs map and index.

Verification

Spec generation verified offline via app.openapi() (61 paths, all routers present).
Curl examples derived from the generated schemas; not executed against a live server (service was not running).

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/niels-emmer/myace/pull/146 **Author:** [@niels-emmer](https://github.com/niels-emmer) **Created:** 8/31/2026 **Status:** ✅ Merged **Merged:** 8/31/2026 **Merged by:** [@niels-emmer](https://github.com/niels-emmer) **Base:** `main` ← **Head:** `docs/api-discoverability` --- ### 📝 Commits (2) - [`78fa907`](https://github.com/niels-emmer/myace/commit/78fa907c4c7a7dbbeb1b7b9bfa9296f34a1f4f7a) docs: add API.md with API discoverability guide - [`edbace7`](https://github.com/niels-emmer/myace/commit/edbace7367da1f945954beb9c6aac550e556daf6) Merge branch 'main' into docs/api-discoverability ### 📊 Changes **3 files changed** (+148 additions, -0 deletions) <details> <summary>View changed files</summary> ➕ `API.md` (+143 -0) 📝 `README.md` (+1 -0) 📝 `docs/README.md` (+4 -0) </details> ### 📄 Description ## Summary Adds `API.md` at the repo root documenting the MyACE HTTP API, following the `api-discoverability-for-agents` skill's discover → document → write-back loop. ## What was found - No `API.md`, OpenAPI spec files, Postman collections, or `.http` files existed in the repo. - The backend (FastAPI) already serves a complete OpenAPI spec at `/openapi.json` — generated for free, served even in production (only the Swagger UI is disabled via `docs_url=None`; `openapi_url` stays at its default). Verified offline: 61 paths, every route covered. - Two discoverability gaps: (1) nothing in the repo pointed agents at the spec; (2) the spec declares no security schemes (auth is a custom `Depends(get_current_user)` dependency), so an agent reading only the spec cannot determine how to authenticate. ## What changed - **`API.md`** (new) — orientation layer on top of the live spec: base URLs, spec endpoints, the two auth mechanisms (flagged as the authoritative auth reference), route-group table, and verified curl examples (register, login, token creation, list collections, compile, demo compile). All request/response shapes pulled from the actual generated schemas. - **`README.md`** / **`docs/README.md`** — linked `API.md` from the docs map and index. ## Verification - Spec generation verified offline via `app.openapi()` (61 paths, all routers present). - Curl examples derived from the generated schemas; not executed against a live server (service was not running). --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

zaph0d

2026-09-01 07:34:18 +02:00