myco-api-endpoint-serializer-authoring

name	myco:api-endpoint-serializer-authoring
managed_by	myco
display_name	API Endpoint and Serializer Authoring (apps/api)
user-invocable	false
description	Apply this skill when adding an endpoint to apps/api/, authoring a mutation-ack serializer, wiring ManagerFactory, resolving Phase 5A routing collisions, or diagnosing the validate_manifest or test_resource_route_coverage CI gates. Covers: resource vs. action classification (409 vs. 200+envelope); Cursor + paginate() pagination in services/pagination.py; ManagerFactory concurrency scoping; apps/api → unifi-core-only dependency rule; Phase 5A patterns (capability-aware dispatch on product_kinds, dual-kind stats, wrapper-dict unwrap, path disambiguation, TOOL_ROUTE_OVERRIDES in test_resource_route_coverage.py); @register_serializer(tools={...}) decorator; seven RenderKind values; field-curation discipline; _reset_registry_for_tests() isolation; and the two CI gates. Post-Phase 6: read tools use Strawberry types (graphql-api-extension skill); serializers cover mutation acks only. Activate even without explicit serializer mention — any apps/api/ PR may need CI-gate alignment.
tags	["api","serializer","routing","endpoint","phase-5a","ci-gates"]
allowed-tools	["Read","Grep","Edit","Write","Bash"]

API Endpoint and Serializer Authoring (apps/api)

A. Adding a Resource or Action Endpoint

1. Classify the endpoint type

• Resource endpoint (GET /v1/sites/{id}/cameras): implies the resource exists; return HTTP 409 when the required product is absent.
• Action endpoint: advisory; always return HTTP 200 with a capability_not_available envelope when the capability is missing — never 404 or 409 for action endpoints.

2. Wire cursor-based pagination

Use Cursor and paginate() from apps/api/src/unifi_api/services/pagination.py:

from unifi_api.services.pagination import Cursor, InvalidCursor, paginate

cursor = Cursor.decode(cursor_str) if cursor_str else None
page, next_cursor = paginate(items, cursor=cursor, limit=limit, key_fn=key_fn)

• Cursor encodes {last_id, last_ts} as Base64 — survives new inserts; offset/page-number pagination does not.
• Default limit 50, max 200. Expose cursor as an opaque query-string param.

3. Apply the dependency rule

apps/api/ MUST only import from unifi-core. Never import unifi-mcp-shared inside apps/api/ — it couples the REST server to MCP protocol concerns.

4. Wire ManagerFactory

ManagerFactory lives in apps/api/src/unifi_api/services/managers.py. It caches one manager per (controller_id, product) pair behind asyncio locks:

manager = await factory.get_connection_manager(session, controller_id, product)

• product_kinds in the DB row is a comma-separated string. The factory splits it and raises UnknownProduct if the product isn't listed — so set product_kinds accurately when registering a controller.
• Each concurrency scope (request) shares the cached manager instance; no per-request teardown.

---

B. Phase 5A Advanced Routing Patterns

Capability-aware dispatch