How to Build a Sports Data FastAPI Gateway with Sportmicro

Description and use

Implemented a FastAPI gateway for Sportmicro that centralizes configuration, hides upstream details, normalizes responses, and handles errors, providing a stable typed interface.

Problem

Directly integrating with a sports data API leaks credentials, response shapes, and error handling into the application, making it fragile and hard to maintain.

Outcome

The gateway provides a stable, typed interface to Sportmicro data, reducing credential leakage, normalizing responses, and centralizing error handling, while keeping the codebase small and testable.

Workflow

• 1. Load settings from environment (SPORTMICRO_API_KEY, base URLs, timeout).
• 2. Instantiate SportmicroClient with async HTTP client and API key.
• 3. Define RESOURCE_MAP linking resource keys to Sportmicro endpoints.
• 4. In route handler, assemble SportmicroQuery from query params.
• 5. Service layer validates resource, translates query to upstream params, fetches data via client.
• 6. Build response with source, endpoint, count, preview items, applied filters, and note if empty.
• 7. Return JSON; on client errors, respond with 502 and retry_after_seconds.

Evidence

The repository is an open‑source example of that shape, powered by Sportmicro.

Source

The app uses a FastAPI lifespan function to create the client once at startup, store the settings and service on app.state, and close the client on shutdown.

Source

The route also handles errors at the edge. If the client raises SportmicroClientError, the app returns a 502‑style JSON response with a detail message and retry_after_seconds: 60.

Source