AGENTS.md

1# API Guidelines
2 
3**Last Updated:** April 9, 2026
4 
5## Handler Conventions
6 
7- Reuse limiter stacks such as `limiter.Auth` and `limiter.Login`, and use `limiter.AbortJSON` for `429` responses.
8- Lean on `api.ClientIP`, `header.BearerToken`, and the shared `Abort*` helpers instead of duplicating request parsing.
9- Compare secrets in constant time and set `Cache-Control: no-store` on sensitive responses.
10- Register routes in `internal/server/routes.go`.
11- New list endpoints should default to `count=100`, cap at `1000`, require `offset >= 0`, and document their parameters explicitly.
12- When a test or fixture needs portal mode, set `PHOTOPRISM_NODE_ROLE=portal` together with `PHOTOPRISM_JOIN_TOKEN`.
13 
14## Roles, Scopes & Sessions
15 
16- Map user roles through `acl.ParseRole(s)` and `acl.UserRoles[...]`; map client roles through `acl.ClientRoles[...]`.
17- Treat `RoleAliasNone` (`none`) and the empty string as `RoleNone`; default unknown client roles to `RoleClient`.
18- When checking JWT or client scopes, use `acl.ScopePermits` and `acl.ScopeAttrPermits` instead of handwritten parsing.
19- Use `AuthenticateAdmin`, `AuthenticateUser`, or `OAuthToken` helpers in tests rather than building auth flows manually.
20- Build client-session requests with `entity.AddClientSession(..., authn.GrantClientCredentials, nil)` and `AuthenticatedRequest(...)`.
21- Admin sessions may see `AdvertiseUrl` and `Database`; client and user sessions must not. `SiteUrl` and the client `storageNamespace` derived from it are safe to expose.
22 
23## Swagger & API Tests
24 
25- Annotate only routed handlers in `internal/api/*.go`; use full `/api/v1/...` paths and skip helper functions.
26- Regenerate API docs with `make fmt-go swag-fmt swag` or `make swag-json`; `make swag` may fetch modules, so confirm network access first.
27- While iterating, prefer focused runs such as `go test ./internal/api -run Cluster -count=1`.
28- Isolate config paths with `t.TempDir()` and reuse `NewConfig`, `CliTestContext`, and `NewApiTest()` helpers.
29- For negative permission checks, prefer OAuth client tokens over non-admin user fixtures.
30- Register `CreateSession(router)` only once per test router; a second registration panics on duplicate routes.
31 
32