Public API

F14.01 10 funcionalidades Plataforma+

En resumen

A first-class Public API surface that exposes federation, ranking, competition, and venue data through a versioned REST contract with auto-generated OpenAPI 3.1 docs, M2M OAuth2 client credentials, per-client and per-IP rate limits, hourly usage analytics, an interactive ERD explorer, and a self-service developer portal for token lifecycle management — built so any integrator can read public petanque data without writing custom code.

Cómo funciona

FastAPI mounts every public route under a /v1/ prefix and emits an X-API-Version header on every response, with X-API-Version-Deprecated returned when callers pin a sunset version. The OpenAPI 3.1 schema is generated at build time, enriched with contact, license, terms, and tag metadata, and rendered as Swagger UI at /docs and ReDoc at /redoc; a lightweight GET /api/info discovery endpoint advertises the spec URL, available scopes, and current version matrix. Machine clients authenticate via RFC 6749 §4.4 client credentials at POST /auth/m2m/token, exchanging a SHA-256-hashed secret for an ES512-signed JWT scoped to the requesting tenant; secrets rotate without downtime and an optional IP CIDR allowlist gates token issuance.

Every request flows through a sliding-window rate limiter that emits X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers; per-IP defaults protect anonymous traffic while per-M2M-client policies range from 1 to 10 000 requests per minute, with an abuse monitor temporarily locking out misbehaving callers. Public read endpoints — /public/rankings, /public/results, /public/venues — use cursor pagination and indexed filters so federation portals can render directly without proxying. Behind the scenes, an ApiUsageRecord aggregates hourly buckets per token, endpoint, and status code; /api-usage/summary, /api-usage/by-token, and /api-usage/timeseries surface latency percentiles and rate-limit hit counts to both tenant admins and the integrating developer.

The developer portal exposes POST /api-tokens for self-service token lifecycle (create, scope, revoke), and an interactive ERD drill-down at /erd lets integrators navigate the data model from super-domain down to entity with fuzzy search, BFS radius, and cross-domain bridges, all driven by JSON endpoints (/erd/domains, /erd/entities/{name}) and a project-configurable SuperDomainConfig.

Capacidades clave

OpenAPI 3.1 contract with Swagger UI, ReDoc, and /api/info discovery
URL-prefix and header-driven API versioning with deprecation signaling
Per-IP and per-M2M-client sliding-window rate limits with abuse lockout
RFC 6749 §4.4 M2M OAuth2 with ES512 JWTs, hashed secrets, and IP allowlists
Cursor-paginated public endpoints for rankings, results, venues
Self-service token lifecycle and per-token usage analytics
Interactive ERD explorer with JSON endpoints and fuzzy entity search

En la práctica

A federation web team needs to render the national ranking on their Next.js site. The lead developer opens the developer portal, creates an M2M client scoped to public:rankings, and downloads the client_id and one-time secret. They POST to /auth/m2m/token, receive a 30-minute ES512 JWT, and call GET /v1/public/rankings?category=Senior&limit=50 with cursor pagination.

The response carries X-RateLimit-Remaining: 4995 and X-API-Version: v1. Browsing /docs they confirm the response shape, copy a curl snippet, and paste it into their integration test. A week later they open /api-usage/by-token to verify p95 latency stays under 120 ms and that no rate-limit hits have occurred, then bump their plan from 1 000 to 5 000 req/min before launch.

Funcionalidades de este subsistema

ID	Status	Funcionalidades
F14.01.01	Entregado	RESTful API with OpenAPI/Swagger documentation — GET /api/info discovery endpoint, enriched OpenAPI metadata (contact, license, terms, tags), Swagger UI at /docs, ReDoc at /redoc ✅ PL-F1401a
F14.01.02	Entregado	API versioning — X-API-Version response header on all responses, /v1/ URL prefix transparency, X-API-Version-Deprecated header for mismatched versions ✅ PL-F1401a
F14.01.03	Entregado	Rate limiting per client — X-RateLimit-Limit/X-RateLimit-Remaining/X-RateLimit-Reset response headers, per-IP sliding window, per-M2M-client configurable limits (1–10 000 req/min), abuse monitor with lockout ✅ PL-F1401a
F14.01.04	Entregado	M2M OAuth2 client credentials authentication — RFC 6749 §4.4 compliant POST /auth/m2m/token, ES512 JWT, SHA-256 secret hashing, IP CIDR allowlist, secret rotation, admin CRUD ✅ PL-F1401a
F14.01.05	Entregado	Public endpoints (rankings, results, calendar, venue directory) — GET /public/rankings, /public/rankings/{id}, /public/results, /public/results/{competition_id}, /public/venues, /public/venues/{id} with cursor pagination, filters, and search ✅ PL-F1401b
F14.01.06	Entregado	API developer portal — POST /api-tokens, scopade M2M-tokens, rate limiting ✅ PL-F1401b
F14.01.07	Entregado	API key management — token-livscykel (create, revoke, validate), SHA-256-hash ✅ PL-F1401b
F14.01.08	Entregado	API usage analytics and monitoring — ApiUsageRecord hourly buckets, GET /api-usage/summary, /api-usage/by-token, /api-usage/timeseries with per-endpoint breakdowns, latency tracking, and rate-limit hit counting ✅ PL-F1401b
F14.01.09	Entregado	ERD drill-down explorer — three-tier /erd viewer (super-domain → sub-domain → entity) with breadcrumb, URL-state, fuzzy search, heatmap, BFS radius 1–2, cross-domain-bridge toggle; new JSON endpoints /erd/domains, /erd/domains/{id}, /erd/entities/{name}; project-configurable F01–F20 mapping via SuperDomainConfig ✅ PL-T097
F14.01.10	Entregado	Service-account M2M-tokens with admin scopes — ServiceAccount-modell, ApiScope admin-scopes (tenants:write, federations:write, cms:write, admin_invitations:create, users:write, seed:run), /sys/service-accounts CRUD + token mint/revoke, 90-day default TTL, agent-driven prod-bootstrap utan WebAuthn-step-up ✅ PL-T293