The admin API described in OpenAPI 3.1: generated from a route table by docgen, served at /api/v1/openapi.json

adminapi.Routes lists every endpoint with its query parameters and Go values
of the bodies it reads and answers with; internal/docgen/openapi turns that
into docs/admin-api.openapi.json by reflection, the way encoding/json encodes
the types, with the fields' comments as descriptions. A test fails when an
endpoint is registered and not in the table, another when the committed
document is stale. The binary embeds it and serves it with the token.

Handlers that wrote map literals and decoded anonymous structs now use named
types, so the document can see them. GET /api/v1/models/{name} answers with a
model's whole definition as it is in force, which a tool managing it needs.
docs/admin-api.md: reaching the API, the token, what a request must carry.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Ilker ManapandClaude Opus 5.5 committed 2026-10-04 23:47:59 +02:00
1 parent 30f7f3474a
commit a95c519bc5
17 files changed
+7643 -62

No files matched your search

+46 -19
View File
@@ -75,13 +75,26 @@ func (a *API) SetRevoker(f func(ctx context.Context, nodeID string, at time.Time
a.revoke = f
}
// Mux is where the endpoints are mounted. An *http.ServeMux is one; a test
// that records the patterns is another, and is how the route table is checked
// against what is actually served.
type Mux interface {
HandleFunc(pattern string, handler func(http.ResponseWriter, *http.Request))
}
// Register mounts the endpoints on a mux under /api/v1.
func (a *API) Register(mux *http.ServeMux) {
//
// Every pattern registered here, or by the register helpers it calls, must
// also be in Routes: that table is what the OpenAPI document is generated
// from, and a test fails when the two disagree.
func (a *API) Register(mux Mux) {
mux.HandleFunc("GET /api/v1/summary", a.summary)
// Adding a model is a write, and the only one this API has. It lives here
// rather than on the client-facing listener for the same reason the rest of
// it does: reaching this port already means holding the control plane.
mux.HandleFunc("GET /api/v1/openapi.json", serveOpenAPI)
// Changes to the catalog live here rather than on the client-facing
// listener for the same reason the rest of this does: reaching this port
// already means holding the control plane.
mux.HandleFunc("POST /api/v1/models", a.addModel)
mux.HandleFunc("GET /api/v1/models/{name}", a.getModel)
mux.HandleFunc("DELETE /api/v1/models/{name}", a.removeModel)
mux.HandleFunc("POST /api/v1/models/{name}/scale", a.scaleModel)
mux.HandleFunc("POST /api/v1/models/{name}/resources", a.setResources)
@@ -97,9 +110,7 @@ func (a *API) Register(mux *http.ServeMux) {
writeError(w, http.StatusNotImplemented, "this control plane has no store")
return
}
var req struct {
Class string `json:"class"`
}
var req ClassRequest
if err := json.NewDecoder(io.LimitReader(r.Body, 1<<12)).Decode(&req); err != nil {
writeError(w, http.StatusBadRequest, "the request is not valid JSON: "+err.Error())
return
@@ -109,7 +120,7 @@ func (a *API) Register(mux *http.ServeMux) {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusOK, map[string]string{"model": m.Name, "class": m.EffectiveClass()})
writeJSON(w, http.StatusOK, ClassView{Model: m.Name, Class: m.EffectiveClass()})
})
mux.HandleFunc("PUT /api/v1/models/{name}/capacity", a.putCapacity)
mux.HandleFunc("GET /api/v1/capacity", a.listCapacity)
@@ -953,7 +964,25 @@ func (a *API) addModel(w http.ResponseWriter, r *http.Request) {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusOK, map[string]string{"added": m.Name})
writeJSON(w, http.StatusOK, ModelAdded{Added: m.Name})
}
// getModel answers with one model's whole definition as it is in force: what
// was added, with the defaults the catalog filled in. The listing shows a
// model's state and only the names of its profiles; this is what a tool
// managing the definition — Terraform, say — compares against what it wants.
//
// By its name only, not an alias: an alias answering would let a tool believe
// a model it manages exists when it is another one.
func (a *API) getModel(w http.ResponseWriter, r *http.Request) {
name := r.PathValue("name")
for _, m := range a.ctl.Catalog().Models() {
if m.Name == name {
writeJSON(w, http.StatusOK, m)
return
}
}
writeError(w, http.StatusNotFound, "no model named "+name+" is in the catalog")
}
// ScaleRequest is how many replicas a model should run.
@@ -1039,7 +1068,7 @@ func (a *API) removeModel(w http.ResponseWriter, r *http.Request) {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusOK, map[string]string{"removed": name})
writeJSON(w, http.StatusOK, Removed{Removed: name})
}
func (a *API) summary(w http.ResponseWriter, _ *http.Request) {
@@ -1137,15 +1166,13 @@ func (a *API) removeNode(w http.ResponseWriter, r *http.Request) {
}
inv.Remove(id)
a.ctl.Reconciler().Notify()
writeJSON(w, http.StatusOK, map[string]string{"id": id, "removed": "true"})
writeJSON(w, http.StatusOK, NodeRemoved{ID: id, Removed: "true"})
}
func (a *API) setNodeState(w http.ResponseWriter, r *http.Request) {
id := r.PathValue("id")
var body struct {
State string `json:"state"`
}
var body NodeStateRequest
if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
writeError(w, http.StatusBadRequest, err.Error())
return
@@ -1173,7 +1200,7 @@ func (a *API) setNodeState(w http.ResponseWriter, r *http.Request) {
// is usually about to do something to it.
a.ctl.Reconciler().Notify()
writeJSON(w, http.StatusOK, map[string]string{"id": id, "state": st.String()})
writeJSON(w, http.StatusOK, NodeStateView{ID: id, State: st.String()})
}
func writeJSON(w http.ResponseWriter, code int, v any) {
@@ -1183,7 +1210,7 @@ func writeJSON(w http.ResponseWriter, code int, v any) {
}
func writeError(w http.ResponseWriter, code int, msg string) {
writeJSON(w, code, map[string]string{"error": msg})
writeJSON(w, code, ErrorView{Error: msg})
}
// profileChanged reports whether a replica is running a profile the catalog no
@@ -1384,7 +1411,7 @@ func (a *API) retryModel(w http.ResponseWriter, r *http.Request) {
return
}
was := a.ctl.Reconciler().Retry(name)
writeJSON(w, http.StatusOK, map[string]bool{"was_parked": was})
writeJSON(w, http.StatusOK, RetryView{WasParked: was})
}
// requestFinder looks a request up by the id it was given. Asked of the usage
@@ -1477,7 +1504,7 @@ func (a *API) upgradeNode(w http.ResponseWriter, r *http.Request) {
writeError(w, http.StatusBadGateway, err.Error())
return
}
writeJSON(w, http.StatusOK, map[string]string{"node": r.PathValue("id"), "version": req.Version})
writeJSON(w, http.StatusOK, UpgradeView{Node: r.PathValue("id"), Version: req.Version})
}
// SetServe supplies what serves a model from the registry.
@@ -1577,7 +1604,7 @@ func (a *API) rollbackModel(w http.ResponseWriter, r *http.Request) {
writeError(w, http.StatusBadRequest, err.Error())
return
}
writeJSON(w, http.StatusOK, map[string]string{"result": msg})
writeJSON(w, http.StatusOK, Result{Result: msg})
}
// OriginRequest names the repository a model's weights came from.