@apifreaks/openapi-specs 0.1.0

package/specs/commodity/commodity-time-series.json

@@ -0,0 +1,329 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Commodities Time Series API",
+    "version": "1.0.0",
+    "description": "Retrieve daily OHLC (open, high, low, close) price data for any supported commodity over a date range of up to 365 days. Accepts one or more comma-separated commodity symbols with a start and end date in YYYY-MM-DD format. Returns a date-indexed object where each date key maps to per-symbol OHLC data. Non-trading days are automatically excluded. Returns a 400 error for invalid dates or a range exceeding 365 days, and a 404 error for unsupported symbols or a date range with no available data.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Commodity Time Series API Server"
+    }
+  ],
+  "paths": {
+    "/commodity/time-series": {
+      "get": {
+        "tags": [
+          "Commodity APIs"
+        ],
+        "summary": "Get commodity price time series",
+        "description": "Returns day-by-day OHLC data for the requested commodity symbols within a date range.",
+        "operationId": "getCommodityTimeSeries",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "description": "Response format. Currently only `json` is supported.",
+            "schema": {
+              "type": "string",
+              "default": "json",
+              "enum": [
+                "json"
+              ]
+            }
+          },
+          {
+            "name": "symbols",
+            "in": "query",
+            "required": true,
+            "description": "Comma-separated list of commodity symbols.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "startDate",
+            "in": "query",
+            "required": true,
+            "description": "Start date in `YYYY-MM-DD` format.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "endDate",
+            "in": "query",
+            "required": true,
+            "description": "End date in `YYYY-MM-DD` format. Maximum range is 365 days.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/CommodityTimeSeriesResponse"
+                },
+                "examples": {
+                  "success": {
+                    "summary": "Successful response",
+                    "value": {
+                      "success": true,
+                      "startDate": "2025-01-06",
+                      "endDate": "2025-01-08",
+                      "rates": {
+                        "2025-01-06": {
+                          "XAU": {
+                            "open": 2649.01,
+                            "high": 2651.33,
+                            "low": 2645.36,
+                            "close": 2646.91
+                          }
+                        },
+                        "2025-01-07": {
+                          "XAU": {
+                            "open": 2662.45,
+                            "high": 2663.06,
+                            "low": 2655.66,
+                            "close": 2658.9
+                          }
+                        },
+                        "2025-01-08": {
+                          "XAU": {
+                            "open": 2669.69,
+                            "high": 2674.68,
+                            "low": 2668.58,
+                            "close": 2671.8
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request \u2014 Missing parameters, invalid dates, or date range exceeded",
+            "content": {
+              "application/json": {
+                "examples": {
+                  "missingSymbols": {
+                    "summary": "Missing required symbols parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/commodity/time-series",
+                      "status": 400,
+                      "timestamp": "2026-07-27T11:38:40.063Z"
+                    }
+                  },
+                  "invalidDate": {
+                    "summary": "Date does not exist on the calendar",
+                    "value": {
+                      "timestamp": "2026-07-27T11:38:41.234Z",
+                      "path": "/rates/time-series",
+                      "code": 400,
+                      "error": "VALIDATION_ERROR",
+                      "message": "Invalid Date: The provided start date or end date does not exist."
+                    }
+                  },
+                  "startAfterEnd": {
+                    "summary": "startDate is after endDate",
+                    "value": {
+                      "timestamp": "2026-07-27T11:38:41.234Z",
+                      "path": "/rates/time-series",
+                      "code": 400,
+                      "error": "VALIDATION_ERROR",
+                      "message": "start date cannot be after end date"
+                    }
+                  },
+                  "dateRangeExceeded": {
+                    "summary": "Date range exceeds 365 days",
+                    "value": {
+                      "timestamp": "2026-07-27T11:38:40.699Z",
+                      "path": "/rates/time-series",
+                      "code": 400,
+                      "error": "VALIDATION_ERROR",
+                      "message": "Date range exceeds the allowed limit."
+                    }
+                  }
+                },
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found - Symbol or data not available",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "symbolNotFound": {
+                    "summary": "Symbol Not Found",
+                    "value": {
+                      "timestamp": "2026-07-27T11:38:41.234Z",
+                      "path": "/rates/time-series",
+                      "code": 404,
+                      "error": "SYMBOL_NOT_FOUND",
+                      "message": "The symbol is not supported, please visit the documentation for a list of supported symbols"
+                    }
+                  },
+                  "dataNotFound": {
+                    "summary": "No data available for the given date range",
+                    "value": {
+                      "timestamp": "2026-07-27T11:38:41.234Z",
+                      "path": "/rates/time-series",
+                      "code": 404,
+                      "error": "DATA_NOT_FOUND",
+                      "message": "No data found for the specified date range"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "CommodityTimeSeriesResponse": {
+        "type": "object",
+        "required": [
+          "success",
+          "startDate",
+          "endDate",
+          "rates"
+        ],
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "`true` for successful requests."
+          },
+          "startDate": {
+            "type": "string",
+            "description": "Start date of the time series (YYYY-MM-DD)."
+          },
+          "endDate": {
+            "type": "string",
+            "description": "End date of the time series (YYYY-MM-DD)."
+          },
+          "rates": {
+            "$ref": "#/components/schemas/CommodityTimeSeriesRates"
+          }
+        },
+        "description": "Commodity time series response containing date-indexed OHLC data per symbol."
+      },
+      "CommodityTimeSeriesRates": {
+        "type": "object",
+        "description": "Map of trading dates to per-symbol OHLC data. Each key is a trading date (YYYY-MM-DD); non-trading days are excluded.",
+        "additionalProperties": {
+          "title": "CommodityTimeSeriesSymbolData",
+          "type": "object",
+          "description": "Map of commodity symbols to their OHLC data for a single trading date. Each key is a commodity symbol (e.g. XAU).",
+          "additionalProperties": {
+            "$ref": "#/components/schemas/CommodityOhlc"
+          }
+        }
+      },
+      "CommodityOhlc": {
+        "type": "object",
+        "description": "OHLC price data for a single commodity on a single trading day.",
+        "required": ["open", "high", "low", "close"],
+        "properties": {
+          "open": {
+            "type": "number",
+            "format": "float",
+            "description": "Opening price on the given date."
+          },
+          "high": {
+            "type": "number",
+            "format": "float",
+            "description": "Highest price on the given date."
+          },
+          "low": {
+            "type": "number",
+            "format": "float",
+            "description": "Lowest price on the given date."
+          },
+          "close": {
+            "type": "number",
+            "format": "float",
+            "description": "Closing price on the given date."
+          }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error envelope returned by the API on failed requests. Gateway-level validation errors populate status; commodity-service errors (date/symbol/data validation) populate code instead — check whichever is present.",
+        "required": ["message"],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type (e.g., Invalid Param Exception, VALIDATION_ERROR, SYMBOL_NOT_FOUND, DATA_NOT_FOUND)."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path (gateway errors) or internal service path (commodity-service errors) that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code. Present on gateway-level errors."
+          },
+          "code": {
+            "type": "integer",
+            "description": "HTTP status code. Present on commodity-service errors instead of status."
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time",
+            "description": "Timestamp when the error occurred (ISO 8601)."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}

package/specs/commodity/historical-commodity-prices.json

@@ -0,0 +1,273 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Historical Commodity Prices, Delivered Simply.",
+    "version": "1.0.0",
+    "description": "Retrieve OHLC (open, high, low, close) price data for any supported commodity on a specific date. Data is available from January 1990 onwards for 130+ commodities. Accepts one or more comma-separated commodity symbols and a date in YYYY-MM-DD format. The response contains the opening, high, low, and closing price for each symbol on the given date. Returns a 400 error for invalid dates and a 404 error for unsupported symbols or missing rates.",
+    "contact": {
+      "name": "APIFreaks Support",
+      "url": "https://apifreaks.com/contact",
+      "email": "support@apifreaks.com"
+    }
+  },
+  "servers": [
+    {
+      "url": "https://api.apifreaks.com/v1.0",
+      "description": "Historical Commodity Prices API Server"
+    }
+  ],
+  "paths": {
+    "/commodity/rates/historical": {
+      "get": {
+        "tags": ["Commodity APIs"],
+        "summary": "Get historical commodity prices",
+        "description": "Returns OHLC price data for the requested commodity symbols on a specific date.",
+        "operationId": "getHistoricalCommodityPrices",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "description": "Response format. Currently only `json` is supported.",
+            "schema": {
+              "type": "string",
+              "default": "json",
+              "enum": ["json"]
+            }
+          },
+          {
+            "name": "symbols",
+            "in": "query",
+            "required": true,
+            "description": "Comma-separated list of commodity symbols.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "date",
+            "in": "query",
+            "required": true,
+            "description": "Date in `YYYY-MM-DD` format. Data available from 1990 onwards.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HistoricalCommodityPricesResponse"
+                },
+                "examples": {
+                  "success": {
+                    "summary": "Successful response",
+                    "value": {
+                      "success": true,
+                      "date": "2025-01-10",
+                      "rates": {
+                        "WTIOIL-SPOT": {
+                          "date": "2025-01-10",
+                          "open": 73.77,
+                          "high": 77.16,
+                          "low": 73.55,
+                          "close": 75.97
+                        },
+                        "XAU": {
+                          "date": "2025-01-10",
+                          "open": 2669.93,
+                          "high": 2697.85,
+                          "low": 2663.61,
+                          "close": 2689.44
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad request - Invalid date format",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "invalidDateFormat": {
+                    "summary": "Invalid date format",
+                    "value": {
+                      "timestamp": 1781792620618,
+                      "status": 400,
+                      "error": "VALIDATION_ERROR",
+                      "message": "Invalid Date Format (YYYY-MM-DD).",
+                      "path": "/v1.0/commodity/rates/historical"
+                    }
+                  },
+                  "dateNotExist": {
+                    "summary": "Date does not exist",
+                    "value": {
+                      "timestamp": 1781792620618,
+                      "status": 400,
+                      "error": "VALIDATION_ERROR",
+                      "message": "Invalid Date: The provided date does not exist.",
+                      "path": "/v1.0/commodity/rates/historical"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found - Symbol or rate not available",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "symbolNotFound": {
+                    "summary": "Symbol Not Found",
+                    "value": {
+                      "timestamp": 1781792620618,
+                      "status": 404,
+                      "error": "SYMBOL_NOT_FOUND",
+                      "message": "The symbol is not supported, please visit the documentation for a list of supported symbols",
+                      "path": "/v1.0/commodity/rates/historical"
+                    }
+                  },
+                  "rateNotFound": {
+                    "summary": "Rate Not Found",
+                    "value": {
+                      "timestamp": 1781792620618,
+                      "status": 404,
+                      "error": "RATE_NOT_FOUND",
+                      "message": "no rates found for the specified date",
+                      "path": "/v1.0/commodity/rates/historical"
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "ApiKeyAuthHeader": {
+        "type": "apiKey",
+        "in": "header",
+        "name": "X-apiKey",
+        "description": "Pass your API key via the X-apiKey request header."
+      },
+      "ApiKeyAuthQuery": {
+        "type": "apiKey",
+        "in": "query",
+        "name": "apiKey",
+        "description": "Pass your API key via the apiKey query parameter."
+      }
+    },
+    "schemas": {
+      "HistoricalCommodityPricesResponse": {
+        "type": "object",
+        "required": ["success", "date", "rates"],
+        "properties": {
+          "success": {
+            "type": "boolean",
+            "description": "`true` for successful requests."
+          },
+          "date": {
+            "type": "string",
+            "description": "Date for which prices were fetched (YYYY-MM-DD)."
+          },
+          "rates": {
+            "$ref": "#/components/schemas/HistoricalCommodityRates"
+          }
+        },
+        "description": "Historical commodity prices response containing success status, date, and OHLC rate data."
+      },
+      "HistoricalCommodityRates": {
+        "type": "object",
+        "description": "Object of commodity symbols to their OHLC price data. Each key is a commodity symbol and the value contains date, open, high, low, and close prices.",
+        "properties": {
+          "symbol": {
+            "$ref": "#/components/schemas/HistoricalCommodityRate"
+          }
+        },
+        "required": ["symbol"]
+      },
+      "HistoricalCommodityRate": {
+        "type": "object",
+        "description": "OHLC price data for a single commodity on a specific date.",
+        "required": ["date", "open", "high", "low", "close"],
+        "properties": {
+          "date": {
+            "type": "string",
+            "description": "Date for which prices were fetched (YYYY-MM-DD)."
+          },
+          "open": {
+            "type": "number",
+            "format": "float",
+            "description": "Opening price on the given date."
+          },
+          "high": {
+            "type": "number",
+            "format": "float",
+            "description": "Highest price recorded on the given date."
+          },
+          "low": {
+            "type": "number",
+            "format": "float",
+            "description": "Lowest price recorded on the given date."
+          },
+          "close": {
+            "type": "number",
+            "format": "float",
+            "description": "Closing price on the given date."
+          }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "required": ["timestamp", "status", "error", "message", "path"],
+        "properties": {
+          "timestamp": {
+            "type": "integer",
+            "description": "Unix timestamp in milliseconds when the error occurred."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "error": {
+            "type": "string",
+            "description": "Specific error type (e.g., SYMBOL_NOT_FOUND, VALIDATION_ERROR)."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path that produced the error."
+          }
+        },
+        "description": "Standard error envelope returned by the API on failed requests."
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}