@apifreaks/openapi-specs 0.1.0 → 0.1.2

package/dist/specs/currency/historical-currency-converter.yaml

@@ -0,0 +1,195 @@
+openapi: 3.1.1
+info:
+  title: Historical Currency Converter API Reference
+  version: 1.0.0
+  description: Convert an amount from one currency to another using exchange rates from a specific historical date. Supports fiat, crypto, and metals. Returns the date, source and target currencies, the historical rate, and the converted amount. All parameters are case-insensitive for both fiat/currency codes and crypto/symbols.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Historical Currency Converter API Server
+paths:
+  /currency/converter/historical/prices:
+    get:
+      tags:
+        - Currency APIs
+      summary: Convert currency with historical rates
+      description: Converts an amount using exchange rates from a specific historical date.
+      operationId: convertHistorical
+      parameters:
+        - name: format
+          in: query
+          required: false
+          description: 'Response format: `json` (default) or `xml`.'
+          schema:
+            type: string
+            enum:
+              - json
+              - xml
+            default: json
+        - name: from
+          in: query
+          required: true
+          description: Source currency code.
+          schema:
+            type: string
+        - name: to
+          in: query
+          required: true
+          description: Target currency code.
+          schema:
+            type: string
+        - name: amount
+          in: query
+          required: false
+          description: Amount to convert, as a decimal. Defaults to `1`. Must be numeric — non-numeric values return a 400 (negative values are accepted despite the error message's wording).
+          schema:
+            type: string
+            default: '1'
+        - 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/HistoricalCurrencyConverterResponse'
+              examples:
+                success:
+                  summary: Successful response
+                  value:
+                    date: '2025-01-10'
+                    from: USD
+                    to: EUR
+                    rate: '0.97620'
+                    givenAmount: '100.0'
+                    convertedAmount: '97.620'
+        '400':
+          description: Bad request - Invalid amount or date format
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                missingParams:
+                  summary: Missing required from/to/date parameter
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/currency/converter/historical/prices
+                    status: 400
+                    timestamp: '2026-07-27T12:07:03.772Z'
+                invalidAmount:
+                  summary: amount is not numeric
+                  value:
+                    timestamp: 1785154024296
+                    status: 400
+                    error: Method Argument Type Mismatch
+                    message: Invalid Amount. Please provide amount in decimal format and greater than 0!
+                    path: /v2.0/convert/historical
+                invalidDateFormat:
+                  summary: date is not in YYYY-MM-DD format
+                  value:
+                    timestamp: 1785154024931
+                    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/convert/historical
+        '404':
+          description: Not found - Currency or date not available
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                dateNotFound:
+                  summary: No data for the given date
+                  value:
+                    timestamp: 1785154025547
+                    status: 404
+                    error: Not Found Exception
+                    message: Rates of provided date 2099-01-01 are not available in our database.
+                    path: /v2.0/convert/historical
+                invalidBase:
+                  summary: from currency not supported
+                  value:
+                    timestamp: 1785154026188
+                    status: 404
+                    error: Not Found Exception
+                    message: Rates of provided currency ZZZ are not available in our database!
+                    path: /v2.0/convert/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:
+    HistoricalCurrencyConverterResponse:
+      type: object
+      required:
+        - date
+        - from
+        - to
+        - rate
+        - givenAmount
+        - convertedAmount
+      properties:
+        date:
+          type: string
+          description: Date and time with timezone (UTC) when the rate was recorded.
+        from:
+          type: string
+          description: Source currency code.
+        to:
+          type: string
+          description: Target currency code.
+        rate:
+          type: string
+          description: Conversion rate from source to target currency.
+        givenAmount:
+          type: string
+          description: The amount provided for conversion.
+        convertedAmount:
+          type: string
+          description: The converted amount in the target currency.
+      description: Historical currency conversion response containing the historical rate and converted amount.
+    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 use a Unix millisecond timestamp and an internal service path instead.
+      required:
+        - message
+      properties:
+        timestamp:
+          type:
+            - string
+            - integer
+          description: Timestamp when the error occurred — ISO 8601 string for gateway errors, Unix milliseconds integer for currency-service errors.
+        status:
+          type: integer
+          description: HTTP status code returned with the error.
+        error:
+          type: string
+          description: Specific error type (e.g., Invalid Param Exception, Method Argument Type Mismatch, 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.
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []

package/dist/specs/currency/historical-currency-rate.yaml

@@ -0,0 +1,180 @@
+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: []