@apifreaks/openapi-specs 0.1.0

package/specs/currency/historical-currency-rate.json

@@ -0,0 +1,246 @@
+{
+  "openapi": "3.1.1",
+  "info": {
+    "title": "Historical Exchange Rate API Reference",
+    "version": "1.0.0",
+    "description": "Get exchange rates for a specific historical date for any base currency. Returns rates for all available currencies or a filtered set of symbols. Supports fiat, crypto, and metals. Accepts a date in YYYY-MM-DD format. Returns a 400 error for a missing/malformed date and a 404 error for unsupported currencies, symbols, or a date 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": "Historical Exchange Rate API Server"
+    }
+  ],
+  "paths": {
+    "/currency/rates/historical": {
+      "get": {
+        "tags": ["Currency APIs"],
+        "summary": "Get historical exchange rates",
+        "description": "Returns exchange rates for a specific historical date.",
+        "operationId": "getHistoricalExchangeRates",
+        "parameters": [
+          {
+            "name": "format",
+            "in": "query",
+            "required": false,
+            "description": "Response format: `json` (default) or `xml`.",
+            "schema": {
+              "type": "string",
+              "enum": ["json", "xml"],
+              "default": "json"
+            }
+          },
+          {
+            "name": "base",
+            "in": "query",
+            "required": false,
+            "description": "Base currency code. Defaults to `USD`. Supports fiat, crypto, and metals.",
+            "schema": {
+              "type": "string",
+              "default": "USD"
+            }
+          },
+          {
+            "name": "symbols",
+            "in": "query",
+            "required": false,
+            "description": "Comma-separated currency codes. Omit to get all available rates.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "date",
+            "in": "query",
+            "required": true,
+            "description": "Historical date in `YYYY-MM-DD` format.",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful operation",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HistoricalExchangeRatesResponse"
+                },
+                "examples": {
+                  "success": {
+                    "summary": "Successful response",
+                    "value": {
+                      "date": "2025-01-10",
+                      "base": "USD",
+                      "rates": {
+                        "EUR": "0.9762",
+                        "PKR": "278.65"
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Bad Request — Missing or malformed date",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "missingDate": {
+                    "summary": "Missing required date parameter",
+                    "value": {
+                      "error": "Invalid Param Exception",
+                      "message": "please pass correct parameters",
+                      "path": "/v1.0/currency/rates/historical",
+                      "status": 400,
+                      "timestamp": "2026-07-27T12:01:57.285Z"
+                    }
+                  },
+                  "invalidDateFormat": {
+                    "summary": "date is not in YYYY-MM-DD format",
+                    "value": {
+                      "timestamp": 1785153717794,
+                      "status": 400,
+                      "error": "Invalid Param Exception",
+                      "message": "Provided Date 10-01-2025 is in invalid format. It should be like  YYYY-MM-DD!",
+                      "path": "/v2.0/rates/historical"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found - Currency, symbol, or date not available",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorResponse"
+                },
+                "examples": {
+                  "dateNotFound": {
+                    "summary": "No data for the given date",
+                    "value": {
+                      "timestamp": 1785153718397,
+                      "status": 404,
+                      "error": "Not Found Exception",
+                      "message": "Rates of provided date 2099-01-01 are not available in our database.",
+                      "path": "/v2.0/rates/historical"
+                    }
+                  },
+                  "invalidBase": {
+                    "summary": "base currency not supported",
+                    "value": {
+                      "timestamp": 1785153718975,
+                      "status": 404,
+                      "error": "Not Found Exception",
+                      "message": "Rates of provided currency ZZZ are not available in our database!",
+                      "path": "/v2.0/rates/historical"
+                    }
+                  },
+                  "invalidSymbols": {
+                    "summary": "symbols not supported",
+                    "value": {
+                      "timestamp": 1785153718975,
+                      "status": 404,
+                      "error": "Not Found Exception",
+                      "message": "Rates of provided Symbols are not available in our database!",
+                      "path": "/v2.0/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": {
+      "HistoricalExchangeRatesResponse": {
+        "type": "object",
+        "description": "Historical exchange rate response containing date, base currency, and rates map.",
+        "required": ["date", "base", "rates"],
+        "properties": {
+          "date": {
+            "type": "string",
+            "description": "The requested historical date (YYYY-MM-DD)."
+          },
+          "base": {
+            "type": "string",
+            "description": "Base currency used for calculating exchange rates."
+          },
+          "rates": {
+            "type": "object",
+            "description": "Map of currency codes to their exchange rate against the base currency on the requested date. Each key is a currency code and the value is an exchange rate string.",
+            "additionalProperties": {
+              "title": "ExchangeRateString",
+              "type": "string",
+              "description": "Exchange rate value as a string for this currency code."
+            }
+          }
+        }
+      },
+      "ErrorResponse": {
+        "type": "object",
+        "description": "Standard error envelope returned by the API on failed requests. Gateway-level validation errors use an ISO 8601 timestamp and the public endpoint path; currency-service errors (date/symbol validation) use a Unix millisecond timestamp and an internal service path instead.",
+        "required": ["message"],
+        "properties": {
+          "error": {
+            "type": "string",
+            "description": "Short error category or exception type (e.g., Invalid Param Exception, Not Found Exception)."
+          },
+          "message": {
+            "type": "string",
+            "description": "Human-readable error message describing the failure."
+          },
+          "path": {
+            "type": "string",
+            "description": "API endpoint path (gateway errors) or internal service path (currency-service errors) that produced the error."
+          },
+          "status": {
+            "type": "integer",
+            "description": "HTTP status code returned with the error."
+          },
+          "timestamp": {
+            "type": ["string", "integer"],
+            "description": "Timestamp when the error occurred — ISO 8601 string for gateway errors, Unix milliseconds integer for currency-service errors."
+          }
+        }
+      }
+    }
+  },
+  "security": [
+    {
+      "ApiKeyAuthHeader": []
+    },
+    {
+      "ApiKeyAuthQuery": []
+    }
+  ]
+}