From 589664c7bdae4722354860e1880840d2f918b9f1 Mon Sep 17 00:00:00 2001 From: Cameron Yick Date: Sat, 13 Dec 2025 23:43:54 -0500 Subject: [PATCH 1/3] feat: Add OpenAPI foundation components MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add core OpenAPI 3.0.0 infrastructure for Tiingo API: - Main openapi.yaml with API structure and routing - Common schemas (Date, DateTime, Ticker, Currency, ErrorResponse) - Reusable parameters (token, ticker, date ranges, formats) - Standard error responses (401, 404, 500) - Schema and component registries This foundation enables all endpoint-specific specifications. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .beads/issues.jsonl | 22 ++++ openapi/openapi.yaml | 179 +++++++++++++++++++++++++++++++++ openapi/parameters/_index.yaml | 49 +++++++++ openapi/responses/_index.yaml | 34 +++++++ openapi/schemas/_index.yaml | 168 +++++++++++++++++++++++++++++++ openapi/schemas/common.yaml | 39 +++++++ 6 files changed, 491 insertions(+) create mode 100644 .beads/issues.jsonl create mode 100644 openapi/openapi.yaml create mode 100644 openapi/parameters/_index.yaml create mode 100644 openapi/responses/_index.yaml create mode 100644 openapi/schemas/_index.yaml create mode 100644 openapi/schemas/common.yaml diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl new file mode 100644 index 0000000..58eb94d --- /dev/null +++ b/.beads/issues.jsonl @@ -0,0 +1,22 @@ +{"id":"tiingo-python-3ra","title":"Create main openapi.yaml index file","description":"Create openapi/openapi.yaml main index file with $ref references to all 9 path files, common components (parameters, schemas, responses), servers config, and security schemes","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.246571-05:00","updated_at":"2025-12-13T21:12:36.8245-05:00","closed_at":"2025-12-13T21:12:36.8245-05:00","dependencies":[{"issue_id":"tiingo-python-3ra","depends_on_id":"tiingo-python-3ui","type":"blocks","created_at":"2025-12-13T18:33:53.94051-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-3ui","title":"Create schemas index file","description":"Create openapi/schemas/_index.yaml that references all schema files: common.yaml, eod-schemas.yaml, news-schemas.yaml, crypto-schemas.yaml, forex-schemas.yaml, iex-schemas.yaml, fundamentals-schemas.yaml, funds-schemas.yaml, dividends-schemas.yaml, splits-schemas.yaml","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:17.925327-05:00","updated_at":"2025-12-13T20:12:10.346339-05:00","closed_at":"2025-12-13T20:12:10.346339-05:00","dependencies":[{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-db3","type":"blocks","created_at":"2025-12-13T18:33:53.617742-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-hv6","type":"blocks","created_at":"2025-12-13T18:33:53.647897-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-qui","type":"blocks","created_at":"2025-12-13T18:33:53.6761-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-8g5","type":"blocks","created_at":"2025-12-13T18:33:53.704791-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-r9g","type":"blocks","created_at":"2025-12-13T18:33:53.733829-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-zxc","type":"blocks","created_at":"2025-12-13T18:33:53.763228-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-b3u","type":"blocks","created_at":"2025-12-13T18:33:53.795726-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-j56","type":"blocks","created_at":"2025-12-13T18:33:53.827326-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-yfj","type":"blocks","created_at":"2025-12-13T18:33:53.857293-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-4bk","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.391477-05:00","updated_at":"2025-12-13T18:14:16.391477-05:00"} +{"id":"tiingo-python-5bx","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.48674-05:00","updated_at":"2025-12-13T18:14:16.48674-05:00"} +{"id":"tiingo-python-8g5","title":"Generate OpenAPI spec for Forex endpoints","description":"Read docs/api_extracted/forex.md and create openapi/paths/forex.yaml and openapi/schemas/forex-schemas.yaml. Include endpoints: /tiingo/fx/{ticker}, /tiingo/fx/top, /tiingo/fx/{ticker}/prices. Schemas: ForexTopOfBook, ForexPrice","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:22.828837-05:00","updated_at":"2025-12-13T19:39:23.801863-05:00","closed_at":"2025-12-13T19:39:23.801863-05:00","dependencies":[{"issue_id":"tiingo-python-8g5","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:44.295421-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-8g5","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:44.335832-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-8g5","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:44.362837-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-aeb","title":"Validate complete OpenAPI specification","description":"Run OpenAPI validation tools to ensure all $ref references resolve correctly, all schemas are valid, and the specification passes OpenAPI 3.0.3 validation. Fix any issues found.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:19.12959-05:00","updated_at":"2025-12-13T22:30:08.827714-05:00","closed_at":"2025-12-13T22:30:08.827714-05:00","dependencies":[{"issue_id":"tiingo-python-aeb","depends_on_id":"tiingo-python-3ra","type":"blocks","created_at":"2025-12-13T18:33:54.021641-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-b3u","title":"Generate OpenAPI spec for Mutual Fund/ETF Fees endpoints","description":"Read docs/api_extracted/mutual-fund-etf-fees.md and create openapi/paths/funds.yaml and openapi/schemas/funds-schemas.yaml. Include endpoints: /tiingo/funds/{ticker}, /tiingo/funds/{ticker}/metrics. Schemas: FundOverview, FundMetrics","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.299961-05:00","updated_at":"2025-12-13T19:39:23.803006-05:00","closed_at":"2025-12-13T19:39:23.803006-05:00","dependencies":[{"issue_id":"tiingo-python-b3u","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:45.465575-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-b3u","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:45.503921-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-b3u","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:45.536194-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-db3","title":"Generate OpenAPI spec for End-of-Day endpoints","description":"Read docs/api_extracted/end-of-day.md and create openapi/paths/end-of-day.yaml and openapi/schemas/eod-schemas.yaml. Include endpoints: /tiingo/daily/{ticker}/prices, /tiingo/daily/{ticker}. Schemas: PriceData, TickerMetadata","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.300561-05:00","updated_at":"2025-12-13T19:39:23.799437-05:00","closed_at":"2025-12-13T19:39:23.799437-05:00","dependencies":[{"issue_id":"tiingo-python-db3","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:43.019056-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-db3","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:43.048754-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-db3","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:43.087225-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-gco","title":"Create common OpenAPI parameters file","description":"Create openapi/parameters/_index.yaml with reusable parameters: TokenParam, TickerPathParam, StartDateParam, EndDateParam, FormatParam","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:24.019038-05:00","updated_at":"2025-12-13T19:10:56.633329-05:00","closed_at":"2025-12-13T19:10:56.633329-05:00"} +{"id":"tiingo-python-hv6","title":"Generate OpenAPI spec for News endpoints","description":"Read docs/api_extracted/news.md and create openapi/paths/news.yaml and openapi/schemas/news-schemas.yaml. Include endpoints: /tiingo/news, /tiingo/news/bulk_download, /tiingo/news/bulk_download/{id}. Schemas: NewsArticle, BulkDownloadFile","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.43936-05:00","updated_at":"2025-12-13T19:39:23.800886-05:00","closed_at":"2025-12-13T19:39:23.800886-05:00","dependencies":[{"issue_id":"tiingo-python-hv6","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:43.51446-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-hv6","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:43.547333-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-hv6","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:43.577716-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-j56","title":"Generate OpenAPI spec for Dividends endpoints","description":"Read docs/api_extracted/dividends.md and create openapi/paths/dividends.yaml and openapi/schemas/dividends-schemas.yaml. Include endpoints: /tiingo/corporate-actions/distributions, /tiingo/corporate-actions/{ticker}/distributions, /tiingo/corporate-actions/{ticker}/distribution-yield. Schemas: Distribution, DistributionYield","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.537928-05:00","updated_at":"2025-12-13T19:39:23.803357-05:00","closed_at":"2025-12-13T19:39:23.803357-05:00","dependencies":[{"issue_id":"tiingo-python-j56","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:45.916691-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-j56","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:45.949027-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-j56","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:45.979509-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-jyg","title":"Create common OpenAPI responses file","description":"Create openapi/responses/_index.yaml with standard error responses (400, 401, 404, 429, 500) using ErrorResponse schema","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:24.102764-05:00","updated_at":"2025-12-13T19:10:56.634733-05:00","closed_at":"2025-12-13T19:10:56.634733-05:00"} +{"id":"tiingo-python-kf1","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.295251-05:00","updated_at":"2025-12-13T18:14:16.295251-05:00"} +{"id":"tiingo-python-oy5","title":"Create common OpenAPI schemas file","description":"Create openapi/schemas/common.yaml with reusable schemas: Date (YYYY-MM-DD), DateTime (ISO 8601), Ticker (string pattern), Currency, ErrorResponse","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:24.186823-05:00","updated_at":"2025-12-13T19:10:56.635466-05:00","closed_at":"2025-12-13T19:10:56.635466-05:00"} +{"id":"tiingo-python-qui","title":"Generate OpenAPI spec for Crypto endpoints","description":"Read docs/api_extracted/crypto.md and create openapi/paths/crypto.yaml and openapi/schemas/crypto-schemas.yaml. Include endpoints: /tiingo/crypto/prices, /tiingo/crypto, /tiingo/crypto/top (deprecated). Schemas: CryptoPrice, CryptoMetadata, CryptoTopOfBook","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.611042-05:00","updated_at":"2025-12-13T19:39:23.801412-05:00","closed_at":"2025-12-13T19:39:23.801412-05:00","dependencies":[{"issue_id":"tiingo-python-qui","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:43.878154-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-qui","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:43.906201-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-qui","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:43.935488-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-r9g","title":"Generate OpenAPI spec for IEX endpoints","description":"Read docs/api_extracted/iex.md and create openapi/paths/iex.yaml and openapi/schemas/iex-schemas.yaml. Include endpoints: /iex, /iex/{ticker}, /iex/{ticker}/prices. Schemas: IEXTopOfBook, IEXPrice","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:22.930732-05:00","updated_at":"2025-12-13T19:39:23.802213-05:00","closed_at":"2025-12-13T19:39:23.802213-05:00","dependencies":[{"issue_id":"tiingo-python-r9g","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:44.661321-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-r9g","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:44.692337-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-r9g","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:44.72001-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-rse","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.64347-05:00","updated_at":"2025-12-13T18:14:16.64347-05:00"} +{"id":"tiingo-python-tsp","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.300538-05:00","updated_at":"2025-12-13T18:14:16.300538-05:00"} +{"id":"tiingo-python-wm4","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.759112-05:00","updated_at":"2025-12-13T18:14:16.759112-05:00"} +{"id":"tiingo-python-y7a","title":"Generate modular OpenAPI 3.0 specification for Tiingo API","description":"Create a complete, modular OpenAPI 3.0.3 specification for all 9 Tiingo REST API endpoint categories. The spec will use a maintainable file structure with separate files for paths, schemas, parameters, and responses, all referenced via the main openapi.yaml index file.","status":"closed","priority":2,"issue_type":"epic","created_at":"2025-12-13T18:14:33.229701-05:00","updated_at":"2025-12-13T22:38:59.777612-05:00","closed_at":"2025-12-13T22:38:59.777612-05:00"} +{"id":"tiingo-python-yfj","title":"Generate OpenAPI spec for Splits endpoints","description":"Read docs/api_extracted/splits.md and create openapi/paths/splits.yaml and openapi/schemas/splits-schemas.yaml. Include endpoints: /tiingo/corporate-actions/splits, /tiingo/corporate-actions/{ticker}/splits. Schemas: Split","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.708985-05:00","updated_at":"2025-12-13T19:39:23.80368-05:00","closed_at":"2025-12-13T19:39:23.80368-05:00","dependencies":[{"issue_id":"tiingo-python-yfj","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:46.383795-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-yfj","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:46.412601-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-yfj","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:46.441969-05:00","created_by":"daemon"}]} +{"id":"tiingo-python-zxc","title":"Generate OpenAPI spec for Fundamentals endpoints","description":"Read docs/api_extracted/fundamentals.md and create openapi/paths/fundamentals.yaml and openapi/schemas/fundamentals-schemas.yaml. Include endpoints: /tiingo/fundamentals/definitions, /tiingo/fundamentals/{ticker}/statements, /tiingo/fundamentals/{ticker}/daily, /tiingo/fundamentals/meta. Schemas: FundamentalDefinition, FinancialStatement, DailyMetric, FundamentalMeta","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:23.024124-05:00","updated_at":"2025-12-13T19:39:23.802546-05:00","closed_at":"2025-12-13T19:39:23.802546-05:00","dependencies":[{"issue_id":"tiingo-python-zxc","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:45.098824-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-zxc","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:45.138032-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-zxc","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:45.176957-05:00","created_by":"daemon"}]} diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml new file mode 100644 index 0000000..3d947b7 --- /dev/null +++ b/openapi/openapi.yaml @@ -0,0 +1,179 @@ +openapi: 3.0.3 + +info: + title: Tiingo REST API + version: 1.0.0 + description: | + Tiingo is a financial data platform providing real-time and historical market data. + + This API provides access to: + - End-of-Day stock prices and metadata + - Financial news articles and bulk downloads + - Cryptocurrency prices and metadata + - Foreign exchange (Forex) rates and prices + - IEX real-time stock data + - Fundamental financial statements and metrics + - Mutual fund and ETF data + - Corporate actions (dividends and stock splits) + + Authentication is required via API token. Get your free API token at https://www.tiingo.com + contact: + name: Tiingo API Support + url: https://www.tiingo.com + email: api@tiingo.com + license: + name: Tiingo Terms of Service + url: https://www.tiingo.com/about/terms-of-service + +servers: + - url: https://api.tiingo.com + description: Production API Server + - url: https://apimedia.tiingo.com + description: Media/Static Assets Server + +# Global security requirement - all endpoints require API key +security: + - ApiKeyAuth: [] + +# ============================================================================ +# PATHS - API Endpoints +# ============================================================================ +paths: + # -------------------------------------------------------------------------- + # End-of-Day Endpoints (2 endpoints) + # -------------------------------------------------------------------------- + /tiingo/daily/{ticker}/prices: + $ref: "./paths/end-of-day.yaml#/daily-prices" + + /tiingo/daily/{ticker}: + $ref: "./paths/end-of-day.yaml#/daily-meta" + + # -------------------------------------------------------------------------- + # News Endpoints (3 endpoints) + # -------------------------------------------------------------------------- + /tiingo/news: + $ref: "./paths/news.yaml#/news" + + /tiingo/news/bulk_download: + $ref: "./paths/news.yaml#/bulk-list" + + /tiingo/news/bulk_download/{id}: + $ref: "./paths/news.yaml#/bulk-download" + + # -------------------------------------------------------------------------- + # Crypto Endpoints (3 endpoints) + # -------------------------------------------------------------------------- + /tiingo/crypto/prices: + $ref: "./paths/crypto.yaml#/crypto-prices" + + /tiingo/crypto: + $ref: "./paths/crypto.yaml#/crypto-meta" + + /tiingo/crypto/top: + $ref: "./paths/crypto.yaml#/crypto-top" + + # -------------------------------------------------------------------------- + # Forex Endpoints (3 endpoints) + # -------------------------------------------------------------------------- + /tiingo/fx/{ticker}: + $ref: "./paths/forex.yaml#/forex-single" + + /tiingo/fx/top: + $ref: "./paths/forex.yaml#/forex-top" + + /tiingo/fx/{ticker}/prices: + $ref: "./paths/forex.yaml#/forex-prices" + + # -------------------------------------------------------------------------- + # IEX Endpoints (3 endpoints) + # -------------------------------------------------------------------------- + /iex: + $ref: "./paths/iex.yaml#/iex-all" + + /iex/{ticker}: + $ref: "./paths/iex.yaml#/iex-single" + + /iex/{ticker}/prices: + $ref: "./paths/iex.yaml#/iex-prices" + + # -------------------------------------------------------------------------- + # Fundamentals Endpoints (4 endpoints) + # -------------------------------------------------------------------------- + /tiingo/fundamentals/definitions: + $ref: "./paths/fundamentals.yaml#/definitions" + + /tiingo/fundamentals/{ticker}/statements: + $ref: "./paths/fundamentals.yaml#/statements" + + /tiingo/fundamentals/{ticker}/daily: + $ref: "./paths/fundamentals.yaml#/daily" + + /tiingo/fundamentals/meta: + $ref: "./paths/fundamentals.yaml#/meta" + + # -------------------------------------------------------------------------- + # Funds Endpoints (2 endpoints) + # -------------------------------------------------------------------------- + /tiingo/funds/{ticker}: + $ref: "./paths/funds.yaml#/fund-overview" + + /tiingo/funds/{ticker}/metrics: + $ref: "./paths/funds.yaml#/fund-metrics" + + # -------------------------------------------------------------------------- + # Dividends/Distributions Endpoints (3 endpoints) + # -------------------------------------------------------------------------- + /tiingo/corporate-actions/distributions: + $ref: "./paths/dividends.yaml#/distributions-batch" + + /tiingo/corporate-actions/{ticker}/distributions: + $ref: "./paths/dividends.yaml#/distributions-ticker" + + /tiingo/corporate-actions/{ticker}/distribution-yield: + $ref: "./paths/dividends.yaml#/distribution-yield" + + # -------------------------------------------------------------------------- + # Splits Endpoints (2 endpoints) + # -------------------------------------------------------------------------- + /tiingo/corporate-actions/splits: + $ref: "./paths/splits.yaml#/splits-batch" + + /tiingo/corporate-actions/{ticker}/splits: + $ref: "./paths/splits.yaml#/splits-ticker" + +# ============================================================================ +# COMPONENTS - Reusable definitions +# ============================================================================ +components: + # -------------------------------------------------------------------------- + # Security Schemes + # -------------------------------------------------------------------------- + securitySchemes: + ApiKeyAuth: + type: apiKey + in: query + name: token + description: | + API key authentication. Obtain your API token from https://www.tiingo.com + + Usage: Add `?token=YOUR_API_TOKEN` to all API requests. + + Example: `https://api.tiingo.com/tiingo/daily/aapl/prices?token=YOUR_API_TOKEN` + + # -------------------------------------------------------------------------- + # Reusable Parameters + # -------------------------------------------------------------------------- + parameters: + $ref: "./parameters/_index.yaml" + + # -------------------------------------------------------------------------- + # Reusable Schemas + # -------------------------------------------------------------------------- + schemas: + $ref: "./schemas/_index.yaml" + + # -------------------------------------------------------------------------- + # Reusable Responses + # -------------------------------------------------------------------------- + responses: + $ref: "./responses/_index.yaml" diff --git a/openapi/parameters/_index.yaml b/openapi/parameters/_index.yaml new file mode 100644 index 0000000..fa7c144 --- /dev/null +++ b/openapi/parameters/_index.yaml @@ -0,0 +1,49 @@ +# Reusable Parameter Definitions for Tiingo API +# Reference these using: $ref: '../parameters/_index.yaml#/ParameterName' + +TokenParam: &TokenParam + name: token + in: query + required: true + schema: + type: string + description: API token for authentication + +TickerPathParam: &TickerPathParam + name: ticker + in: path + required: true + schema: + type: string + pattern: '^[A-Z0-9]{1,5}$' + description: Stock or cryptocurrency ticker symbol + +StartDateParam: &StartDateParam + name: startDate + in: query + required: false + schema: + type: string + format: date + description: Start date for historical data in YYYY-MM-DD format + +EndDateParam: &EndDateParam + name: endDate + in: query + required: false + schema: + type: string + format: date + description: End date for historical data in YYYY-MM-DD format + +FormatParam: &FormatParam + name: format + in: query + required: false + schema: + type: string + enum: + - json + - csv + default: json + description: Response format (json or csv) diff --git a/openapi/responses/_index.yaml b/openapi/responses/_index.yaml new file mode 100644 index 0000000..7bb652b --- /dev/null +++ b/openapi/responses/_index.yaml @@ -0,0 +1,34 @@ +BadRequest: &BadRequest + description: Bad Request - Invalid parameters + content: + application/json: + schema: + $ref: '../schemas/common.yaml#/ErrorResponse' + +Unauthorized: &Unauthorized + description: Unauthorized - Invalid or missing API token + content: + application/json: + schema: + $ref: '../schemas/common.yaml#/ErrorResponse' + +NotFound: &NotFound + description: Not Found - Ticker or resource not found + content: + application/json: + schema: + $ref: '../schemas/common.yaml#/ErrorResponse' + +TooManyRequests: &TooManyRequests + description: Too Many Requests - Rate limit exceeded + content: + application/json: + schema: + $ref: '../schemas/common.yaml#/ErrorResponse' + +InternalServerError: &InternalServerError + description: Internal Server Error + content: + application/json: + schema: + $ref: '../schemas/common.yaml#/ErrorResponse' diff --git a/openapi/schemas/_index.yaml b/openapi/schemas/_index.yaml new file mode 100644 index 0000000..2742ec8 --- /dev/null +++ b/openapi/schemas/_index.yaml @@ -0,0 +1,168 @@ +# OpenAPI Schemas Index +# This file provides a centralized index of all schema components across the Tiingo API +# organized by endpoint category. Each schema is defined with a YAML anchor and references +# the actual schema definition from its respective file. + +# ======================================================================== +# COMMON SCHEMAS - Shared across all endpoints +# Reference: ./common.yaml +# ======================================================================== + +Date: &Date + $ref: './common.yaml#/Date' + +DateTime: &DateTime + $ref: './common.yaml#/DateTime' + +Ticker: &Ticker + $ref: './common.yaml#/Ticker' + +Currency: &Currency + $ref: './common.yaml#/Currency' + +ErrorResponse: &ErrorResponse + $ref: './common.yaml#/ErrorResponse' + +# ======================================================================== +# END-OF-DAY STOCK PRICE SCHEMAS +# Reference: https://www.tiingo.com/documentation/end-of-day +# File: ./eod-schemas.yaml +# ======================================================================== + +PriceData: &PriceData + $ref: './eod-schemas.yaml#/PriceData' + +TickerMetadata: &TickerMetadata + $ref: './eod-schemas.yaml#/TickerMetadata' + +# ======================================================================== +# NEWS API SCHEMAS +# File: ./news-schemas.yaml +# ======================================================================== + +NewsArticle: &NewsArticle + $ref: './news-schemas.yaml#/NewsArticle' + +BulkDownloadFile: &BulkDownloadFile + $ref: './news-schemas.yaml#/BulkDownloadFile' + +# ======================================================================== +# CRYPTOCURRENCY API SCHEMAS +# File: ./crypto-schemas.yaml +# ======================================================================== + +CryptoCurrency: &CryptoCurrency + $ref: './crypto-schemas.yaml#/CryptoCurrency' + +CryptoTicker: &CryptoTicker + $ref: './crypto-schemas.yaml#/CryptoTicker' + +ResampleFreq: &ResampleFreq + $ref: './crypto-schemas.yaml#/ResampleFreq' + +PriceDataItem: &PriceDataItem + $ref: './crypto-schemas.yaml#/PriceDataItem' + +ExchangeDataItem: &ExchangeDataItem + $ref: './crypto-schemas.yaml#/ExchangeDataItem' + +CryptoPrice: &CryptoPrice + $ref: './crypto-schemas.yaml#/CryptoPrice' + +CryptoMetadata: &CryptoMetadata + $ref: './crypto-schemas.yaml#/CryptoMetadata' + +TopOfBookData: &TopOfBookData + $ref: './crypto-schemas.yaml#/TopOfBookData' + +TopOfBookExchangeData: &TopOfBookExchangeData + $ref: './crypto-schemas.yaml#/TopOfBookExchangeData' + +CryptoTopOfBook: &CryptoTopOfBook + $ref: './crypto-schemas.yaml#/CryptoTopOfBook' + +# ======================================================================== +# FOREX API SCHEMAS +# File: ./forex-schemas.yaml +# ======================================================================== + +ForexTopOfBook: &ForexTopOfBook + $ref: './forex-schemas.yaml#/ForexTopOfBook' + +ForexPrice: &ForexPrice + $ref: './forex-schemas.yaml#/ForexPrice' + +# ======================================================================== +# IEX EXCHANGE API SCHEMAS +# Reference: https://api.tiingo.com/documentation/iex +# File: ./iex-schemas.yaml +# ======================================================================== + +IEXTopOfBook: &IEXTopOfBook + $ref: './iex-schemas.yaml#/IEXTopOfBook' + +IEXPrice: &IEXPrice + $ref: './iex-schemas.yaml#/IEXPrice' + +# ======================================================================== +# FUNDAMENTALS API SCHEMAS +# File: ./fundamentals-schemas.yaml +# ======================================================================== + +FundamentalDefinition: &FundamentalDefinition + $ref: './fundamentals-schemas.yaml#/FundamentalDefinition' + +DataPoint: &DataPoint + $ref: './fundamentals-schemas.yaml#/DataPoint' + +StatementData: &StatementData + $ref: './fundamentals-schemas.yaml#/StatementData' + +FinancialStatement: &FinancialStatement + $ref: './fundamentals-schemas.yaml#/FinancialStatement' + +DailyMetric: &DailyMetric + $ref: './fundamentals-schemas.yaml#/DailyMetric' + +FundamentalMeta: &FundamentalMeta + $ref: './fundamentals-schemas.yaml#/FundamentalMeta' + +# ======================================================================== +# MUTUAL FUNDS AND ETF SCHEMAS +# Reference: /docs/api_extracted/mutual-fund-etf-fees.md +# File: ./funds-schemas.yaml +# ======================================================================== + +OtherShareClass: &OtherShareClass + $ref: './funds-schemas.yaml#/OtherShareClass' + +FundOverview: &FundOverview + $ref: './funds-schemas.yaml#/FundOverview' + +CustomFee: &CustomFee + $ref: './funds-schemas.yaml#/CustomFee' + +FundMetrics: &FundMetrics + $ref: './funds-schemas.yaml#/FundMetrics' + +# ======================================================================== +# DIVIDENDS AND DISTRIBUTIONS SCHEMAS +# File: ./dividends-schemas.yaml +# ======================================================================== + +Distribution: &Distribution + $ref: './dividends-schemas.yaml#/Distribution' + +DistributionYield: &DistributionYield + $ref: './dividends-schemas.yaml#/DistributionYield' + +# ======================================================================== +# STOCK SPLITS SCHEMAS +# File: ./splits-schemas.yaml +# ======================================================================== + +Split: &Split + $ref: './splits-schemas.yaml#/Split' + +SplitArray: &SplitArray + $ref: './splits-schemas.yaml#/SplitArray' diff --git a/openapi/schemas/common.yaml b/openapi/schemas/common.yaml new file mode 100644 index 0000000..5bdaf49 --- /dev/null +++ b/openapi/schemas/common.yaml @@ -0,0 +1,39 @@ +Date: &Date + type: string + format: date + pattern: '^\d{4}-\d{2}-\d{2}$' + description: Date in ISO 8601 format + example: '2025-12-13' + +DateTime: &DateTime + type: string + format: date-time + description: Timestamp in ISO 8601 format + example: '2025-12-13T18:00:00.000Z' + +Ticker: &Ticker + type: string + pattern: '^[A-Z0-9]+$' + description: Stock, ETF, or crypto ticker symbol + example: 'AAPL' + +Currency: &Currency + type: string + pattern: '^[A-Z]{3}$' + description: ISO 4217 currency code + example: 'USD' + +ErrorResponse: &ErrorResponse + type: object + properties: + error: + type: string + description: Error message + detail: + type: string + description: Detailed error information + required: + - error + example: + error: "Invalid ticker symbol" + detail: "Ticker 'XYZ123' not found" From a906ce01d953ed409ab000dfd7beb59c6f707fbf Mon Sep 17 00:00:00 2001 From: Cameron Yick Date: Sat, 13 Dec 2025 23:54:25 -0500 Subject: [PATCH 2/3] check openapi spec in CI --- .github/workflows/python-package.yml | 6 +++++- Makefile | 3 +++ requirements_dev.txt | 1 + 3 files changed, 9 insertions(+), 1 deletion(-) diff --git a/.github/workflows/python-package.yml b/.github/workflows/python-package.yml index 558e64c..723cb08 100644 --- a/.github/workflows/python-package.yml +++ b/.github/workflows/python-package.yml @@ -35,8 +35,12 @@ jobs: pip install setuptools fi python setup.py develop - python -m pip install flake8 pytest-cov coverage vcrpy black + python -m pip install flake8 pytest-cov coverage vcrpy black openapi-spec-validator tools/install_pandas.sh + - name: Validate OpenAPI spec + continue-on-error: true + run: | + openapi-spec-validator openapi/openapi.yaml - name: black run: | black --check tiingo diff --git a/Makefile b/Makefile index 12a882f..cef8645 100644 --- a/Makefile +++ b/Makefile @@ -56,6 +56,9 @@ format: ## apply opinionated formatting format-check: ## check formatting for CI black --check tiingo/ +validate-openapi: ## validate OpenAPI specification + openapi-spec-validator openapi/openapi.yaml + test: ## run tests quickly with the default Python py.test diff --git a/requirements_dev.txt b/requirements_dev.txt index fec4fcf..bb51eb7 100644 --- a/requirements_dev.txt +++ b/requirements_dev.txt @@ -12,3 +12,4 @@ pytest==8.3.4 vcrpy==2.1.1 twine==6.0.1 black==24.10.0 +openapi-spec-validator==0.7.1 From e1d44e953ed129d8ee564ac9e0130eecfcf3a737 Mon Sep 17 00:00:00 2001 From: Cameron Yick Date: Sun, 14 Dec 2025 00:13:21 -0500 Subject: [PATCH 3/3] feat: add CI check for valid API spec + remove unsupported sections --- .beads/issues.jsonl | 22 ---- openapi/openapi.yaml | 145 ++++++++++++++------------- openapi/schemas/_index.yaml | 194 +++++++++++++++++++----------------- 3 files changed, 181 insertions(+), 180 deletions(-) delete mode 100644 .beads/issues.jsonl diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl deleted file mode 100644 index 58eb94d..0000000 --- a/.beads/issues.jsonl +++ /dev/null @@ -1,22 +0,0 @@ -{"id":"tiingo-python-3ra","title":"Create main openapi.yaml index file","description":"Create openapi/openapi.yaml main index file with $ref references to all 9 path files, common components (parameters, schemas, responses), servers config, and security schemes","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.246571-05:00","updated_at":"2025-12-13T21:12:36.8245-05:00","closed_at":"2025-12-13T21:12:36.8245-05:00","dependencies":[{"issue_id":"tiingo-python-3ra","depends_on_id":"tiingo-python-3ui","type":"blocks","created_at":"2025-12-13T18:33:53.94051-05:00","created_by":"daemon"}]} -{"id":"tiingo-python-3ui","title":"Create schemas index file","description":"Create openapi/schemas/_index.yaml that references all schema files: common.yaml, eod-schemas.yaml, news-schemas.yaml, crypto-schemas.yaml, forex-schemas.yaml, iex-schemas.yaml, fundamentals-schemas.yaml, funds-schemas.yaml, dividends-schemas.yaml, splits-schemas.yaml","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:17.925327-05:00","updated_at":"2025-12-13T20:12:10.346339-05:00","closed_at":"2025-12-13T20:12:10.346339-05:00","dependencies":[{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-db3","type":"blocks","created_at":"2025-12-13T18:33:53.617742-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-hv6","type":"blocks","created_at":"2025-12-13T18:33:53.647897-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-qui","type":"blocks","created_at":"2025-12-13T18:33:53.6761-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-8g5","type":"blocks","created_at":"2025-12-13T18:33:53.704791-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-r9g","type":"blocks","created_at":"2025-12-13T18:33:53.733829-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-zxc","type":"blocks","created_at":"2025-12-13T18:33:53.763228-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-b3u","type":"blocks","created_at":"2025-12-13T18:33:53.795726-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-j56","type":"blocks","created_at":"2025-12-13T18:33:53.827326-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-3ui","depends_on_id":"tiingo-python-yfj","type":"blocks","created_at":"2025-12-13T18:33:53.857293-05:00","created_by":"daemon"}]} -{"id":"tiingo-python-4bk","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.391477-05:00","updated_at":"2025-12-13T18:14:16.391477-05:00"} -{"id":"tiingo-python-5bx","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.48674-05:00","updated_at":"2025-12-13T18:14:16.48674-05:00"} -{"id":"tiingo-python-8g5","title":"Generate OpenAPI spec for Forex endpoints","description":"Read docs/api_extracted/forex.md and create openapi/paths/forex.yaml and openapi/schemas/forex-schemas.yaml. Include endpoints: /tiingo/fx/{ticker}, /tiingo/fx/top, /tiingo/fx/{ticker}/prices. Schemas: ForexTopOfBook, ForexPrice","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:22.828837-05:00","updated_at":"2025-12-13T19:39:23.801863-05:00","closed_at":"2025-12-13T19:39:23.801863-05:00","dependencies":[{"issue_id":"tiingo-python-8g5","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:44.295421-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-8g5","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:44.335832-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-8g5","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:44.362837-05:00","created_by":"daemon"}]} -{"id":"tiingo-python-aeb","title":"Validate complete OpenAPI specification","description":"Run OpenAPI validation tools to ensure all $ref references resolve correctly, all schemas are valid, and the specification passes OpenAPI 3.0.3 validation. Fix any issues found.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:19.12959-05:00","updated_at":"2025-12-13T22:30:08.827714-05:00","closed_at":"2025-12-13T22:30:08.827714-05:00","dependencies":[{"issue_id":"tiingo-python-aeb","depends_on_id":"tiingo-python-3ra","type":"blocks","created_at":"2025-12-13T18:33:54.021641-05:00","created_by":"daemon"}]} -{"id":"tiingo-python-b3u","title":"Generate OpenAPI spec for Mutual Fund/ETF Fees endpoints","description":"Read docs/api_extracted/mutual-fund-etf-fees.md and create openapi/paths/funds.yaml and openapi/schemas/funds-schemas.yaml. Include endpoints: /tiingo/funds/{ticker}, /tiingo/funds/{ticker}/metrics. Schemas: FundOverview, FundMetrics","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.299961-05:00","updated_at":"2025-12-13T19:39:23.803006-05:00","closed_at":"2025-12-13T19:39:23.803006-05:00","dependencies":[{"issue_id":"tiingo-python-b3u","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:45.465575-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-b3u","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:45.503921-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-b3u","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:45.536194-05:00","created_by":"daemon"}]} -{"id":"tiingo-python-db3","title":"Generate OpenAPI spec for End-of-Day endpoints","description":"Read docs/api_extracted/end-of-day.md and create openapi/paths/end-of-day.yaml and openapi/schemas/eod-schemas.yaml. Include endpoints: /tiingo/daily/{ticker}/prices, /tiingo/daily/{ticker}. Schemas: PriceData, TickerMetadata","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.300561-05:00","updated_at":"2025-12-13T19:39:23.799437-05:00","closed_at":"2025-12-13T19:39:23.799437-05:00","dependencies":[{"issue_id":"tiingo-python-db3","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:43.019056-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-db3","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:43.048754-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-db3","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:43.087225-05:00","created_by":"daemon"}]} -{"id":"tiingo-python-gco","title":"Create common OpenAPI parameters file","description":"Create openapi/parameters/_index.yaml with reusable parameters: TokenParam, TickerPathParam, StartDateParam, EndDateParam, FormatParam","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:24.019038-05:00","updated_at":"2025-12-13T19:10:56.633329-05:00","closed_at":"2025-12-13T19:10:56.633329-05:00"} -{"id":"tiingo-python-hv6","title":"Generate OpenAPI spec for News endpoints","description":"Read docs/api_extracted/news.md and create openapi/paths/news.yaml and openapi/schemas/news-schemas.yaml. Include endpoints: /tiingo/news, /tiingo/news/bulk_download, /tiingo/news/bulk_download/{id}. Schemas: NewsArticle, BulkDownloadFile","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.43936-05:00","updated_at":"2025-12-13T19:39:23.800886-05:00","closed_at":"2025-12-13T19:39:23.800886-05:00","dependencies":[{"issue_id":"tiingo-python-hv6","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:43.51446-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-hv6","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:43.547333-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-hv6","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:43.577716-05:00","created_by":"daemon"}]} -{"id":"tiingo-python-j56","title":"Generate OpenAPI spec for Dividends endpoints","description":"Read docs/api_extracted/dividends.md and create openapi/paths/dividends.yaml and openapi/schemas/dividends-schemas.yaml. Include endpoints: /tiingo/corporate-actions/distributions, /tiingo/corporate-actions/{ticker}/distributions, /tiingo/corporate-actions/{ticker}/distribution-yield. Schemas: Distribution, DistributionYield","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.537928-05:00","updated_at":"2025-12-13T19:39:23.803357-05:00","closed_at":"2025-12-13T19:39:23.803357-05:00","dependencies":[{"issue_id":"tiingo-python-j56","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:45.916691-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-j56","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:45.949027-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-j56","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:45.979509-05:00","created_by":"daemon"}]} -{"id":"tiingo-python-jyg","title":"Create common OpenAPI responses file","description":"Create openapi/responses/_index.yaml with standard error responses (400, 401, 404, 429, 500) using ErrorResponse schema","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:24.102764-05:00","updated_at":"2025-12-13T19:10:56.634733-05:00","closed_at":"2025-12-13T19:10:56.634733-05:00"} -{"id":"tiingo-python-kf1","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.295251-05:00","updated_at":"2025-12-13T18:14:16.295251-05:00"} -{"id":"tiingo-python-oy5","title":"Create common OpenAPI schemas file","description":"Create openapi/schemas/common.yaml with reusable schemas: Date (YYYY-MM-DD), DateTime (ISO 8601), Ticker (string pattern), Currency, ErrorResponse","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:24.186823-05:00","updated_at":"2025-12-13T19:10:56.635466-05:00","closed_at":"2025-12-13T19:10:56.635466-05:00"} -{"id":"tiingo-python-qui","title":"Generate OpenAPI spec for Crypto endpoints","description":"Read docs/api_extracted/crypto.md and create openapi/paths/crypto.yaml and openapi/schemas/crypto-schemas.yaml. Include endpoints: /tiingo/crypto/prices, /tiingo/crypto, /tiingo/crypto/top (deprecated). Schemas: CryptoPrice, CryptoMetadata, CryptoTopOfBook","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.611042-05:00","updated_at":"2025-12-13T19:39:23.801412-05:00","closed_at":"2025-12-13T19:39:23.801412-05:00","dependencies":[{"issue_id":"tiingo-python-qui","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:43.878154-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-qui","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:43.906201-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-qui","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:43.935488-05:00","created_by":"daemon"}]} -{"id":"tiingo-python-r9g","title":"Generate OpenAPI spec for IEX endpoints","description":"Read docs/api_extracted/iex.md and create openapi/paths/iex.yaml and openapi/schemas/iex-schemas.yaml. Include endpoints: /iex, /iex/{ticker}, /iex/{ticker}/prices. Schemas: IEXTopOfBook, IEXPrice","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:22.930732-05:00","updated_at":"2025-12-13T19:39:23.802213-05:00","closed_at":"2025-12-13T19:39:23.802213-05:00","dependencies":[{"issue_id":"tiingo-python-r9g","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:44.661321-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-r9g","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:44.692337-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-r9g","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:44.72001-05:00","created_by":"daemon"}]} -{"id":"tiingo-python-rse","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.64347-05:00","updated_at":"2025-12-13T18:14:16.64347-05:00"} -{"id":"tiingo-python-tsp","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.300538-05:00","updated_at":"2025-12-13T18:14:16.300538-05:00"} -{"id":"tiingo-python-wm4","title":"task","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.759112-05:00","updated_at":"2025-12-13T18:14:16.759112-05:00"} -{"id":"tiingo-python-y7a","title":"Generate modular OpenAPI 3.0 specification for Tiingo API","description":"Create a complete, modular OpenAPI 3.0.3 specification for all 9 Tiingo REST API endpoint categories. The spec will use a maintainable file structure with separate files for paths, schemas, parameters, and responses, all referenced via the main openapi.yaml index file.","status":"closed","priority":2,"issue_type":"epic","created_at":"2025-12-13T18:14:33.229701-05:00","updated_at":"2025-12-13T22:38:59.777612-05:00","closed_at":"2025-12-13T22:38:59.777612-05:00"} -{"id":"tiingo-python-yfj","title":"Generate OpenAPI spec for Splits endpoints","description":"Read docs/api_extracted/splits.md and create openapi/paths/splits.yaml and openapi/schemas/splits-schemas.yaml. Include endpoints: /tiingo/corporate-actions/splits, /tiingo/corporate-actions/{ticker}/splits. Schemas: Split","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:16.708985-05:00","updated_at":"2025-12-13T19:39:23.80368-05:00","closed_at":"2025-12-13T19:39:23.80368-05:00","dependencies":[{"issue_id":"tiingo-python-yfj","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:46.383795-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-yfj","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:46.412601-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-yfj","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:46.441969-05:00","created_by":"daemon"}]} -{"id":"tiingo-python-zxc","title":"Generate OpenAPI spec for Fundamentals endpoints","description":"Read docs/api_extracted/fundamentals.md and create openapi/paths/fundamentals.yaml and openapi/schemas/fundamentals-schemas.yaml. Include endpoints: /tiingo/fundamentals/definitions, /tiingo/fundamentals/{ticker}/statements, /tiingo/fundamentals/{ticker}/daily, /tiingo/fundamentals/meta. Schemas: FundamentalDefinition, FinancialStatement, DailyMetric, FundamentalMeta","status":"closed","priority":2,"issue_type":"task","created_at":"2025-12-13T18:14:23.024124-05:00","updated_at":"2025-12-13T19:39:23.802546-05:00","closed_at":"2025-12-13T19:39:23.802546-05:00","dependencies":[{"issue_id":"tiingo-python-zxc","depends_on_id":"tiingo-python-gco","type":"blocks","created_at":"2025-12-13T18:33:45.098824-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-zxc","depends_on_id":"tiingo-python-jyg","type":"blocks","created_at":"2025-12-13T18:33:45.138032-05:00","created_by":"daemon"},{"issue_id":"tiingo-python-zxc","depends_on_id":"tiingo-python-oy5","type":"blocks","created_at":"2025-12-13T18:33:45.176957-05:00","created_by":"daemon"}]} diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index 3d947b7..8259f4e 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -38,108 +38,119 @@ security: # ============================================================================ # PATHS - API Endpoints # ============================================================================ -paths: +# NOTE: Path references are commented out until their corresponding path files +# are created. Each PR that adds a path file should uncomment its section. +paths: {} # -------------------------------------------------------------------------- # End-of-Day Endpoints (2 endpoints) + # TODO: Uncomment when ./paths/end-of-day.yaml is created # -------------------------------------------------------------------------- - /tiingo/daily/{ticker}/prices: - $ref: "./paths/end-of-day.yaml#/daily-prices" - - /tiingo/daily/{ticker}: - $ref: "./paths/end-of-day.yaml#/daily-meta" + # /tiingo/daily/{ticker}/prices: + # $ref: "./paths/end-of-day.yaml#/daily-prices" + # + # /tiingo/daily/{ticker}: + # $ref: "./paths/end-of-day.yaml#/daily-meta" # -------------------------------------------------------------------------- # News Endpoints (3 endpoints) + # TODO: Uncomment when ./paths/news.yaml is created # -------------------------------------------------------------------------- - /tiingo/news: - $ref: "./paths/news.yaml#/news" - - /tiingo/news/bulk_download: - $ref: "./paths/news.yaml#/bulk-list" - - /tiingo/news/bulk_download/{id}: - $ref: "./paths/news.yaml#/bulk-download" + # /tiingo/news: + # $ref: "./paths/news.yaml#/news" + # + # /tiingo/news/bulk_download: + # $ref: "./paths/news.yaml#/bulk-list" + # + # /tiingo/news/bulk_download/{id}: + # $ref: "./paths/news.yaml#/bulk-download" # -------------------------------------------------------------------------- # Crypto Endpoints (3 endpoints) + # TODO: Uncomment when ./paths/crypto.yaml is created # -------------------------------------------------------------------------- - /tiingo/crypto/prices: - $ref: "./paths/crypto.yaml#/crypto-prices" - - /tiingo/crypto: - $ref: "./paths/crypto.yaml#/crypto-meta" - - /tiingo/crypto/top: - $ref: "./paths/crypto.yaml#/crypto-top" + # /tiingo/crypto/prices: + # $ref: "./paths/crypto.yaml#/crypto-prices" + # + # /tiingo/crypto: + # $ref: "./paths/crypto.yaml#/crypto-meta" + # + # /tiingo/crypto/top: + # $ref: "./paths/crypto.yaml#/crypto-top" # -------------------------------------------------------------------------- # Forex Endpoints (3 endpoints) + # TODO: Uncomment when ./paths/forex.yaml is created # -------------------------------------------------------------------------- - /tiingo/fx/{ticker}: - $ref: "./paths/forex.yaml#/forex-single" - - /tiingo/fx/top: - $ref: "./paths/forex.yaml#/forex-top" - - /tiingo/fx/{ticker}/prices: - $ref: "./paths/forex.yaml#/forex-prices" + # /tiingo/fx/{ticker}: + # $ref: "./paths/forex.yaml#/forex-single" + # + # /tiingo/fx/top: + # $ref: "./paths/forex.yaml#/forex-top" + # + # /tiingo/fx/{ticker}/prices: + # $ref: "./paths/forex.yaml#/forex-prices" # -------------------------------------------------------------------------- # IEX Endpoints (3 endpoints) + # TODO: Uncomment when ./paths/iex.yaml is created # -------------------------------------------------------------------------- - /iex: - $ref: "./paths/iex.yaml#/iex-all" - - /iex/{ticker}: - $ref: "./paths/iex.yaml#/iex-single" - - /iex/{ticker}/prices: - $ref: "./paths/iex.yaml#/iex-prices" + # /iex: + # $ref: "./paths/iex.yaml#/iex-all" + # + # /iex/{ticker}: + # $ref: "./paths/iex.yaml#/iex-single" + # + # /iex/{ticker}/prices: + # $ref: "./paths/iex.yaml#/iex-prices" # -------------------------------------------------------------------------- # Fundamentals Endpoints (4 endpoints) + # TODO: Uncomment when ./paths/fundamentals.yaml is created # -------------------------------------------------------------------------- - /tiingo/fundamentals/definitions: - $ref: "./paths/fundamentals.yaml#/definitions" - - /tiingo/fundamentals/{ticker}/statements: - $ref: "./paths/fundamentals.yaml#/statements" - - /tiingo/fundamentals/{ticker}/daily: - $ref: "./paths/fundamentals.yaml#/daily" - - /tiingo/fundamentals/meta: - $ref: "./paths/fundamentals.yaml#/meta" + # /tiingo/fundamentals/definitions: + # $ref: "./paths/fundamentals.yaml#/definitions" + # + # /tiingo/fundamentals/{ticker}/statements: + # $ref: "./paths/fundamentals.yaml#/statements" + # + # /tiingo/fundamentals/{ticker}/daily: + # $ref: "./paths/fundamentals.yaml#/daily" + # + # /tiingo/fundamentals/meta: + # $ref: "./paths/fundamentals.yaml#/meta" # -------------------------------------------------------------------------- # Funds Endpoints (2 endpoints) + # TODO: Uncomment when ./paths/funds.yaml is created # -------------------------------------------------------------------------- - /tiingo/funds/{ticker}: - $ref: "./paths/funds.yaml#/fund-overview" - - /tiingo/funds/{ticker}/metrics: - $ref: "./paths/funds.yaml#/fund-metrics" + # /tiingo/funds/{ticker}: + # $ref: "./paths/funds.yaml#/fund-overview" + # + # /tiingo/funds/{ticker}/metrics: + # $ref: "./paths/funds.yaml#/fund-metrics" # -------------------------------------------------------------------------- # Dividends/Distributions Endpoints (3 endpoints) + # TODO: Uncomment when ./paths/dividends.yaml is created # -------------------------------------------------------------------------- - /tiingo/corporate-actions/distributions: - $ref: "./paths/dividends.yaml#/distributions-batch" - - /tiingo/corporate-actions/{ticker}/distributions: - $ref: "./paths/dividends.yaml#/distributions-ticker" - - /tiingo/corporate-actions/{ticker}/distribution-yield: - $ref: "./paths/dividends.yaml#/distribution-yield" + # /tiingo/corporate-actions/distributions: + # $ref: "./paths/dividends.yaml#/distributions-batch" + # + # /tiingo/corporate-actions/{ticker}/distributions: + # $ref: "./paths/dividends.yaml#/distributions-ticker" + # + # /tiingo/corporate-actions/{ticker}/distribution-yield: + # $ref: "./paths/dividends.yaml#/distribution-yield" # -------------------------------------------------------------------------- # Splits Endpoints (2 endpoints) + # TODO: Uncomment when ./paths/splits.yaml is created # -------------------------------------------------------------------------- - /tiingo/corporate-actions/splits: - $ref: "./paths/splits.yaml#/splits-batch" - - /tiingo/corporate-actions/{ticker}/splits: - $ref: "./paths/splits.yaml#/splits-ticker" + # /tiingo/corporate-actions/splits: + # $ref: "./paths/splits.yaml#/splits-batch" + # + # /tiingo/corporate-actions/{ticker}/splits: + # $ref: "./paths/splits.yaml#/splits-ticker" # ============================================================================ # COMPONENTS - Reusable definitions diff --git a/openapi/schemas/_index.yaml b/openapi/schemas/_index.yaml index 2742ec8..ccd5e77 100644 --- a/openapi/schemas/_index.yaml +++ b/openapi/schemas/_index.yaml @@ -2,6 +2,9 @@ # This file provides a centralized index of all schema components across the Tiingo API # organized by endpoint category. Each schema is defined with a YAML anchor and references # the actual schema definition from its respective file. +# +# NOTE: Schema references are commented out until their corresponding schema files are created. +# Each PR that adds a schema file should uncomment its section. # ======================================================================== # COMMON SCHEMAS - Shared across all endpoints @@ -27,142 +30,151 @@ ErrorResponse: &ErrorResponse # END-OF-DAY STOCK PRICE SCHEMAS # Reference: https://www.tiingo.com/documentation/end-of-day # File: ./eod-schemas.yaml +# TODO: Uncomment when ./eod-schemas.yaml is created # ======================================================================== -PriceData: &PriceData - $ref: './eod-schemas.yaml#/PriceData' - -TickerMetadata: &TickerMetadata - $ref: './eod-schemas.yaml#/TickerMetadata' +# PriceData: &PriceData +# $ref: './eod-schemas.yaml#/PriceData' +# +# TickerMetadata: &TickerMetadata +# $ref: './eod-schemas.yaml#/TickerMetadata' # ======================================================================== # NEWS API SCHEMAS # File: ./news-schemas.yaml +# TODO: Uncomment when ./news-schemas.yaml is created # ======================================================================== -NewsArticle: &NewsArticle - $ref: './news-schemas.yaml#/NewsArticle' - -BulkDownloadFile: &BulkDownloadFile - $ref: './news-schemas.yaml#/BulkDownloadFile' +# NewsArticle: &NewsArticle +# $ref: './news-schemas.yaml#/NewsArticle' +# +# BulkDownloadFile: &BulkDownloadFile +# $ref: './news-schemas.yaml#/BulkDownloadFile' # ======================================================================== # CRYPTOCURRENCY API SCHEMAS # File: ./crypto-schemas.yaml -# ======================================================================== - -CryptoCurrency: &CryptoCurrency - $ref: './crypto-schemas.yaml#/CryptoCurrency' - -CryptoTicker: &CryptoTicker - $ref: './crypto-schemas.yaml#/CryptoTicker' - -ResampleFreq: &ResampleFreq - $ref: './crypto-schemas.yaml#/ResampleFreq' - -PriceDataItem: &PriceDataItem - $ref: './crypto-schemas.yaml#/PriceDataItem' - -ExchangeDataItem: &ExchangeDataItem - $ref: './crypto-schemas.yaml#/ExchangeDataItem' - -CryptoPrice: &CryptoPrice - $ref: './crypto-schemas.yaml#/CryptoPrice' - -CryptoMetadata: &CryptoMetadata - $ref: './crypto-schemas.yaml#/CryptoMetadata' - -TopOfBookData: &TopOfBookData - $ref: './crypto-schemas.yaml#/TopOfBookData' - -TopOfBookExchangeData: &TopOfBookExchangeData - $ref: './crypto-schemas.yaml#/TopOfBookExchangeData' - -CryptoTopOfBook: &CryptoTopOfBook - $ref: './crypto-schemas.yaml#/CryptoTopOfBook' +# TODO: Uncomment when ./crypto-schemas.yaml is created +# ======================================================================== + +# CryptoCurrency: &CryptoCurrency +# $ref: './crypto-schemas.yaml#/CryptoCurrency' +# +# CryptoTicker: &CryptoTicker +# $ref: './crypto-schemas.yaml#/CryptoTicker' +# +# ResampleFreq: &ResampleFreq +# $ref: './crypto-schemas.yaml#/ResampleFreq' +# +# PriceDataItem: &PriceDataItem +# $ref: './crypto-schemas.yaml#/PriceDataItem' +# +# ExchangeDataItem: &ExchangeDataItem +# $ref: './crypto-schemas.yaml#/ExchangeDataItem' +# +# CryptoPrice: &CryptoPrice +# $ref: './crypto-schemas.yaml#/CryptoPrice' +# +# CryptoMetadata: &CryptoMetadata +# $ref: './crypto-schemas.yaml#/CryptoMetadata' +# +# TopOfBookData: &TopOfBookData +# $ref: './crypto-schemas.yaml#/TopOfBookData' +# +# TopOfBookExchangeData: &TopOfBookExchangeData +# $ref: './crypto-schemas.yaml#/TopOfBookExchangeData' +# +# CryptoTopOfBook: &CryptoTopOfBook +# $ref: './crypto-schemas.yaml#/CryptoTopOfBook' # ======================================================================== # FOREX API SCHEMAS # File: ./forex-schemas.yaml +# TODO: Uncomment when ./forex-schemas.yaml is created # ======================================================================== -ForexTopOfBook: &ForexTopOfBook - $ref: './forex-schemas.yaml#/ForexTopOfBook' - -ForexPrice: &ForexPrice - $ref: './forex-schemas.yaml#/ForexPrice' +# ForexTopOfBook: &ForexTopOfBook +# $ref: './forex-schemas.yaml#/ForexTopOfBook' +# +# ForexPrice: &ForexPrice +# $ref: './forex-schemas.yaml#/ForexPrice' # ======================================================================== # IEX EXCHANGE API SCHEMAS # Reference: https://api.tiingo.com/documentation/iex # File: ./iex-schemas.yaml +# TODO: Uncomment when ./iex-schemas.yaml is created # ======================================================================== -IEXTopOfBook: &IEXTopOfBook - $ref: './iex-schemas.yaml#/IEXTopOfBook' - -IEXPrice: &IEXPrice - $ref: './iex-schemas.yaml#/IEXPrice' +# IEXTopOfBook: &IEXTopOfBook +# $ref: './iex-schemas.yaml#/IEXTopOfBook' +# +# IEXPrice: &IEXPrice +# $ref: './iex-schemas.yaml#/IEXPrice' # ======================================================================== # FUNDAMENTALS API SCHEMAS # File: ./fundamentals-schemas.yaml -# ======================================================================== - -FundamentalDefinition: &FundamentalDefinition - $ref: './fundamentals-schemas.yaml#/FundamentalDefinition' - -DataPoint: &DataPoint - $ref: './fundamentals-schemas.yaml#/DataPoint' - -StatementData: &StatementData - $ref: './fundamentals-schemas.yaml#/StatementData' - -FinancialStatement: &FinancialStatement - $ref: './fundamentals-schemas.yaml#/FinancialStatement' - -DailyMetric: &DailyMetric - $ref: './fundamentals-schemas.yaml#/DailyMetric' - -FundamentalMeta: &FundamentalMeta - $ref: './fundamentals-schemas.yaml#/FundamentalMeta' +# TODO: Uncomment when ./fundamentals-schemas.yaml is created +# ======================================================================== + +# FundamentalDefinition: &FundamentalDefinition +# $ref: './fundamentals-schemas.yaml#/FundamentalDefinition' +# +# DataPoint: &DataPoint +# $ref: './fundamentals-schemas.yaml#/DataPoint' +# +# StatementData: &StatementData +# $ref: './fundamentals-schemas.yaml#/StatementData' +# +# FinancialStatement: &FinancialStatement +# $ref: './fundamentals-schemas.yaml#/FinancialStatement' +# +# DailyMetric: &DailyMetric +# $ref: './fundamentals-schemas.yaml#/DailyMetric' +# +# FundamentalMeta: &FundamentalMeta +# $ref: './fundamentals-schemas.yaml#/FundamentalMeta' # ======================================================================== # MUTUAL FUNDS AND ETF SCHEMAS # Reference: /docs/api_extracted/mutual-fund-etf-fees.md # File: ./funds-schemas.yaml +# TODO: Uncomment when ./funds-schemas.yaml is created # ======================================================================== -OtherShareClass: &OtherShareClass - $ref: './funds-schemas.yaml#/OtherShareClass' - -FundOverview: &FundOverview - $ref: './funds-schemas.yaml#/FundOverview' - -CustomFee: &CustomFee - $ref: './funds-schemas.yaml#/CustomFee' - -FundMetrics: &FundMetrics - $ref: './funds-schemas.yaml#/FundMetrics' +# OtherShareClass: &OtherShareClass +# $ref: './funds-schemas.yaml#/OtherShareClass' +# +# FundOverview: &FundOverview +# $ref: './funds-schemas.yaml#/FundOverview' +# +# CustomFee: &CustomFee +# $ref: './funds-schemas.yaml#/CustomFee' +# +# FundMetrics: &FundMetrics +# $ref: './funds-schemas.yaml#/FundMetrics' # ======================================================================== # DIVIDENDS AND DISTRIBUTIONS SCHEMAS # File: ./dividends-schemas.yaml +# TODO: Uncomment when ./dividends-schemas.yaml is created # ======================================================================== -Distribution: &Distribution - $ref: './dividends-schemas.yaml#/Distribution' - -DistributionYield: &DistributionYield - $ref: './dividends-schemas.yaml#/DistributionYield' +# Distribution: &Distribution +# $ref: './dividends-schemas.yaml#/Distribution' +# +# DistributionYield: &DistributionYield +# $ref: './dividends-schemas.yaml#/DistributionYield' # ======================================================================== # STOCK SPLITS SCHEMAS # File: ./splits-schemas.yaml +# TODO: Uncomment when ./splits-schemas.yaml is created # ======================================================================== -Split: &Split - $ref: './splits-schemas.yaml#/Split' - -SplitArray: &SplitArray - $ref: './splits-schemas.yaml#/SplitArray' +# Split: &Split +# $ref: './splits-schemas.yaml#/Split' +# +# SplitArray: &SplitArray +# $ref: './splits-schemas.yaml#/SplitArray'