feat: Add OpenAPI foundation components

.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

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
 

openapi/openapi.yaml

@@ -0,0 +1,190 @@
+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
+# ============================================================================
+# 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"
+
+  # --------------------------------------------------------------------------
+  # 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"
+
+  # --------------------------------------------------------------------------
+  # 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"
+
+  # --------------------------------------------------------------------------
+  # 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"
+
+  # --------------------------------------------------------------------------
+  # 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"
+
+  # --------------------------------------------------------------------------
+  # 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"
+
+  # --------------------------------------------------------------------------
+  # 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"
+
+  # --------------------------------------------------------------------------
+  # 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"
+
+  # --------------------------------------------------------------------------
+  # 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"
+
+# ============================================================================
+# 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"

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)

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'