Architecture

PyMLB StatsAPI uses a config-driven, schema-based architecture where all MLB API endpoints are defined as JSON schemas rather than hardcoded Python classes.

Core Design Pattern

Schema-Driven API Wrapper

The library uses JSON schemas to define MLB API endpoints, enabling:

  • Dynamic endpoint discovery

  • Self-documenting API methods

  • Easy updates when MLB API changes

  • Automatic parameter validation

Key Components

Schema System

Located in pymlb_statsapi/resources/schemas/:

  • endpoint-model.json: Master configuration mapping endpoint names to paths and method names

  • schemas/statsapi/stats_api_1_0/*.json: Individual endpoint schemas with full parameter definitions

Each JSON schema defines:

  • Available operations (methods)

  • Parameters (path vs query)

  • Validation rules

  • Documentation

Model Layer

Base Models (model/factory.py):

  • DynamicEndpoint: Base class for all endpoint models

  • EndpointMethod: Represents individual API operations

  • APIResponse: Response wrapper with metadata

Dynamic Factory (model/factory.py):

  • Generates endpoint classes and methods from schemas at runtime

  • Creates clean function signatures with proper parameter handling

  • Handles method overloading

Registry (model/registry.py):

  • Central api singleton that loads all endpoints

  • Provides discovery API for exploring available methods

Clean API Pattern

The “Clean API” intelligently routes parameters to path or query parameters based on each method’s schema configuration. Developers simply pass parameters as keyword arguments:

# Library automatically determines parameter types from schema
response = api.Game.liveGameV1(game_pk="747175", timecode="20241027_000000")
# Resolves to: /api/v1/game/747175/feed/live?timecode=20241027_000000

Data Flow

  1. User calls api.Schedule.schedule(sportId=1, date="2025-06-01")

  2. Registry returns ScheduleModel instance (loaded from schedule.json schema)

  3. .schedule() method looks up configuration in endpoint-model.json

  4. Returns APIResponse with:

    • Endpoint model

    • API definition from schema

    • Operation with parameter rules

    • Resolved URL: https://statsapi.mlb.com/api/v1/schedule?sportId=1&date=2025-06-01

  5. Response includes .json(), .save_json(), .get_uri() methods

Configuration

The architecture is controlled by:

  • endpoint-model.json: Endpoint to path mappings

  • Individual schema files: Operation definitions and parameter rules

  • Environment variables: PYMLB_STATSAPI__BASE_FILE_PATH, etc.

This design enables the library to adapt to MLB API changes by simply updating JSON schemas, with no code modifications required.