@apifreaks/openapi-specs 0.1.0 → 0.1.2

package/dist/specs/currency/currency-fluctuation.yaml

@@ -0,0 +1,211 @@
+openapi: 3.1.1
+info:
+  title: Currency Fluctuation API - Get Currency Fluctuations Over a Time Period
+  version: 1.0.0
+  description: Get exchange rate fluctuation data between two dates for one or more currency pairs. Returns the start rate, end rate, absolute change, and percentage change for each requested symbol. Accepts a base currency (defaults to USD) and optional comma-separated target symbols. Returns a 400 error for invalid dates and a 404 error when no data is available for the interval.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Currency Fluctuation API Server
+paths:
+  /currency/fluctuation:
+    get:
+      tags:
+        - Currency APIs
+      summary: Get exchange rate fluctuations
+      description: Returns exchange rate fluctuations between two dates for the requested symbols.
+      operationId: getFluctuation
+      parameters:
+        - name: format
+          in: query
+          required: false
+          description: 'Response format: `json` (default) or `xml`.'
+          schema:
+            type: string
+            enum:
+              - json
+              - xml
+            default: json
+        - name: startDate
+          in: query
+          required: true
+          description: Start date in `YYYY-MM-DD` format.
+          schema:
+            type: string
+        - name: endDate
+          in: query
+          required: false
+          description: End date in `YYYY-MM-DD` format. Defaults to yesterday.
+          schema:
+            type: string
+        - name: base
+          in: query
+          required: false
+          description: Base currency code. Defaults to `USD`.
+          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
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CurrencyFluctuationResponse'
+              examples:
+                success:
+                  summary: Successful response
+                  value:
+                    startDate: '2025-01-01'
+                    endDate: '2025-01-10'
+                    base: USD
+                    rateFluctuations:
+                      EUR:
+                        startRate: '0.96605'
+                        endRate: '0.97620'
+                        change: '-0.010150'
+                        percentChange: '-1.05'
+                      PKR:
+                        startRate: '278.400'
+                        endRate: '278.650'
+                        change: '-0.25'
+                        percentChange: '-0.09'
+        '400':
+          description: Bad request - Invalid dates
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                missingStartDate:
+                  summary: Missing required startDate parameter
+                  value:
+                    error: Invalid Param Exception
+                    message: please pass correct parameters
+                    path: /v1.0/currency/fluctuation
+                    status: 400
+                    timestamp: '2026-07-27T12:09:21.348Z'
+                startAfterEnd:
+                  summary: startDate is after endDate or the current date
+                  value:
+                    timestamp: 1785154172736
+                    status: 400
+                    error: Invalid Param Exception
+                    message: Starting date cannot be after current date or ending date
+                    path: /v2.0/fluctuation
+                invalidDateFormat:
+                  summary: startDate/endDate not in YYYY-MM-DD format
+                  value:
+                    timestamp: 1785154172225
+                    status: 400
+                    error: Invalid Param Exception
+                    message: Provided Dates are in Invalid Format. Dates must be in a valid format YYYY-MM-DD!
+                    path: /v2.0/fluctuation
+        '404':
+          description: Not found - No data for interval
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                noData:
+                  summary: base or symbols not supported for the given interval
+                  value:
+                    timestamp: 1785154173332
+                    status: 404
+                    error: Not Found Exception
+                    message: Rates of provided base and symbols are not found for given intervals.
+                    path: /v2.0/fluctuation
+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:
+    CurrencyFluctuationResponse:
+      type: object
+      required:
+        - startDate
+        - endDate
+        - base
+        - rateFluctuations
+      properties:
+        startDate:
+          type: string
+          description: Start date of the interval (YYYY-MM-DD).
+        endDate:
+          type: string
+          description: End date of the interval (YYYY-MM-DD).
+        base:
+          type: string
+          description: Base currency used for all fluctuations.
+        rateFluctuations:
+          type: object
+          description: Map of currency codes to their fluctuation details. Each key is a currency code and the value contains startRate, endRate, change, and percentChange.
+          additionalProperties:
+            title: CurrencyFluctuationItem
+            $ref: '#/components/schemas/CurrencyFluctuationItem'
+      description: Currency fluctuation response containing rate changes per symbol over a date interval.
+    CurrencyFluctuationItem:
+      type: object
+      description: Fluctuation metrics for a single currency over a date interval.
+      required:
+        - startRate
+        - endRate
+        - change
+        - percentChange
+      properties:
+        startRate:
+          type: string
+          description: Rate of the currency at the start of the interval.
+        endRate:
+          type: string
+          description: Rate of the currency at the end of the interval.
+        change:
+          type: string
+          description: Absolute change between start and end rate. Can be positive or negative.
+        percentChange:
+          type: string
+          description: Percentage change between start and end rate. Can be positive or negative.
+    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, 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/currency-historical-data-limit.yaml

@@ -0,0 +1,112 @@
+openapi: 3.1.1
+info:
+  title: Currency Historical Data Limits API Reference
+  version: 1.0.0
+  description: Retrieve the date range for which historical exchange rate data is available for each supported currency. Returns a map of currency codes to their availability period in YYYY-MM-DD to YYYY-MM-DD format. Covers fiat currencies, cryptocurrencies, and precious metals.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Currency Historical Data Limits API Server
+paths:
+  /currency/historical/data/limits:
+    get:
+      tags:
+        - Currency APIs
+      summary: Get historical data availability limits
+      description: Returns the date range when historical data is available for each currency.
+      operationId: getHistoricalDataLimits
+      parameters:
+        - name: format
+          in: query
+          required: false
+          description: 'Response format: `json` (default) or `xml`.'
+          schema:
+            type: string
+            enum:
+              - json
+              - xml
+            default: json
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HistoricalDataLimitsResponse'
+              examples:
+                success:
+                  summary: Successful response
+                  value:
+                    availabilityPeriod:
+                      FJD: 1989-08-18 to 2026-07-27
+                      SCR: 1998-07-31 to 2026-07-27
+                      STPT: 2025-02-27 to 2025-05-28
+        '406':
+          description: Unsupported Media Type — format is not json or xml
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                badFormat:
+                  summary: format value not supported
+                  value:
+                    error: Unsupported Media Type
+                    message: The media type specified in the request is not supported. For more details, please refer to the API documentation.
+                    path: /v1.0/currency/historical/data/limits
+                    status: 406
+                    timestamp: '2026-07-27T12:14:01.189Z'
+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:
+    HistoricalDataLimitsResponse:
+      type: object
+      required:
+        - availabilityPeriod
+      properties:
+        availabilityPeriod:
+          type: object
+          description: Map of currency codes to their historical data availability range. Each key is a currency code and the value is a date range string.
+          additionalProperties:
+            title: AvailabilityPeriodString
+            type: string
+            description: Historical data availability date range in YYYY-MM-DD to YYYY-MM-DD format.
+      description: Historical data limits response containing the availability period map.
+    ErrorResponse:
+      type: object
+      description: Standard error envelope returned by the API on failed requests.
+      required:
+        - message
+      properties:
+        error:
+          type: string
+          description: Short error category or exception type.
+        message:
+          type: string
+          description: Human-readable error message describing the failure.
+        path:
+          type: string
+          description: API endpoint path that produced the error.
+        status:
+          type: integer
+          description: HTTP status code returned with the error.
+        timestamp:
+          type: string
+          format: date-time
+          description: Timestamp when the error occurred (ISO 8601).
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []

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

@@ -0,0 +1,173 @@
+openapi: 3.1.1
+info:
+  title: Exchange Rate API - Real-Time Forex & Crypto Rates for 1,000+ Assets
+  version: 1.0.0
+  description: Get the latest exchange rates for any base currency. Returns rates for all available currencies or a filtered set of symbols. Supports fiat, crypto, and metals. Accepts an optional updates parameter for rate freshness (1m, 10m, 1h, 1d). Returns a 400 error for invalid parameters and a 404 error for unsupported currencies or symbols.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Exchange Rate API Server
+paths:
+  /currency/rates/latest:
+    get:
+      tags:
+        - Currency APIs
+      summary: Get the latest exchange rates
+      description: Returns the latest exchange rates for the requested base currency and symbols.
+      operationId: getLatestExchangeRates
+      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: updates
+          in: query
+          required: false
+          description: 'Update frequency: `1m` (default), `10m`, `1h`, or `1d`.'
+          schema:
+            type: string
+            enum:
+              - 1m
+              - 10m
+              - 1h
+              - 1d
+            default: 1m
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LatestExchangeRatesResponse'
+              examples:
+                success:
+                  summary: Successful response
+                  value:
+                    date: '2026-07-27 12:01:00+00'
+                    base: USD
+                    rates:
+                      EUR: '0.878156'
+                      PKR: '277.863'
+        '400':
+          description: Bad request - Invalid parameters
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                invalidUpdates:
+                  summary: updates is not one of 1m/10m/1h/1d
+                  value:
+                    timestamp: 1785153665906
+                    status: 400
+                    error: Invalid Param Exception
+                    message: Please provide valid updates parameter (1d,1h,10m,1m)
+                    path: /v2.0/rates/latest
+        '404':
+          description: Not found - Currency or symbol not available
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                invalidBase:
+                  summary: base currency not supported
+                  value:
+                    timestamp: 1785153666449
+                    status: 404
+                    error: Not Found Exception
+                    message: Rates of provided currency ZZZ are not available in our database!
+                    path: /v2.0/rates/latest
+                invalidSymbols:
+                  summary: symbols not supported
+                  value:
+                    timestamp: 1785153666998
+                    status: 404
+                    error: Not Found Exception
+                    message: Rates of provided Symbols are not available in our database!
+                    path: /v2.0/rates/latest
+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:
+    LatestExchangeRatesResponse:
+      type: object
+      required:
+        - date
+        - base
+        - rates
+      properties:
+        date:
+          type: string
+          description: Date and time with timezone (UTC) when the rates were recorded.
+        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. 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.
+      description: Exchange rate response containing date, base currency, and rates map.
+    ErrorResponse:
+      type: object
+      required:
+        - timestamp
+        - status
+        - error
+        - message
+        - path
+      properties:
+        timestamp:
+          type: integer
+          format: int64
+          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., `Invalid Param Exception`, `Not Found Exception`).
+        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: []

package/dist/specs/currency/currency-supported.yaml

@@ -0,0 +1,176 @@
+openapi: 3.1.1
+info:
+  title: Currency Supported API Reference
+  version: 1.0.0
+  description: Retrieve the complete list of all supported currencies with full metadata. Returns a map of currency codes to objects containing currency name, country code, country name, availability status, date range, and icon URL. Covers fiat currencies, cryptocurrencies, and precious metals.
+  contact:
+    name: APIFreaks Support
+    url: https://apifreaks.com/contact
+    email: support@apifreaks.com
+servers:
+  - url: https://api.apifreaks.com/v1.0
+    description: Currency Supported API Server
+paths:
+  /currency/supported:
+    get:
+      tags:
+        - Currency APIs
+      summary: Get all supported currencies
+      description: Returns a map of all supported currencies with metadata.
+      operationId: getSupportedCurrencies
+      parameters:
+        - name: format
+          in: query
+          required: false
+          description: 'Response format: `json` (default) or `xml`.'
+          schema:
+            type: string
+            enum:
+              - json
+              - xml
+            default: json
+      responses:
+        '200':
+          description: Successful operation
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SupportedCurrenciesResponse'
+              examples:
+                success:
+                  summary: Successful response
+                  value:
+                    supportedCurrenciesMap:
+                      USD:
+                        currencyCode: USD
+                        currencyName: US Dollar
+                        countryCode: AS
+                        countryName: American Samoa
+                        status: AVAILABLE
+                        availableFrom: '2020-01-01'
+                        availableUntil: '2026-06-18'
+                        icon: https://currencyfreaks.com/photos/flags/usd.png
+                      BTC:
+                        currencyCode: BTC
+                        currencyName: Bitcoin
+                        countryCode: Crypto
+                        countryName: Global
+                        status: AVAILABLE
+                        availableFrom: '2014-01-01'
+                        availableUntil: '2026-06-18'
+                        icon: https://currencyfreaks.com/photos/flags/btc.png
+                      XAU:
+                        currencyCode: XAU
+                        currencyName: Gold Ounce
+                        countryCode: Metal
+                        countryName: Precious Metal
+                        status: AVAILABLE
+                        availableFrom: '2020-01-01'
+                        availableUntil: '2026-06-18'
+                        icon: https://currencyfreaks.com/photos/flags/xau.png
+        '406':
+          description: Unsupported Media Type — format is not json or xml
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+              examples:
+                badFormat:
+                  summary: format value not supported
+                  value:
+                    error: Unsupported Media Type
+                    message: The media type specified in the request is not supported. For more details, please refer to the API documentation.
+                    path: /v1.0/currency/supported
+                    status: 406
+                    timestamp: '2026-07-27T12:12:35.587Z'
+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:
+    SupportedCurrenciesResponse:
+      type: object
+      required:
+        - supportedCurrenciesMap
+      properties:
+        supportedCurrenciesMap:
+          type: object
+          description: Map of all supported currencies keyed by currency code. Each key is a currency code and the value contains full currency metadata.
+          additionalProperties:
+            title: CurrencySupportedItem
+            $ref: '#/components/schemas/CurrencySupportedItem'
+      description: Currency supported response containing the map of all supported currencies.
+    CurrencySupportedItem:
+      type: object
+      description: Metadata for a single supported currency.
+      required:
+        - currencyCode
+        - currencyName
+        - countryCode
+        - countryName
+        - status
+        - availableFrom
+        - availableUntil
+        - icon
+      properties:
+        currencyCode:
+          type: string
+          description: Unique currency code (e.g., USD, BTC, XAU).
+        currencyName:
+          type: string
+          description: Full name of the currency.
+        countryCode:
+          type: string
+          description: 'ISO 3166-1 alpha-2 country code. For crypto: Crypto. For metals: Metal.'
+        countryName:
+          type: string
+          description: 'Country name. For crypto: Global. For metals: Precious Metal.'
+        status:
+          type: string
+          enum:
+            - AVAILABLE
+            - DEPRECIATED
+          description: Availability status.
+        availableFrom:
+          type: string
+          description: Date the currency became available (YYYY-MM-DD).
+        availableUntil:
+          type: string
+          description: Date the currency is or was available (YYYY-MM-DD).
+        icon:
+          type: string
+          format: uri
+          description: URL of the currency icon/flag image.
+    ErrorResponse:
+      type: object
+      description: Standard error envelope returned by the API on failed requests.
+      required:
+        - message
+      properties:
+        error:
+          type: string
+          description: Short error category or exception type.
+        message:
+          type: string
+          description: Human-readable error message describing the failure.
+        path:
+          type: string
+          description: API endpoint path that produced the error.
+        status:
+          type: integer
+          description: HTTP status code returned with the error.
+        timestamp:
+          type: string
+          format: date-time
+          description: Timestamp when the error occurred (ISO 8601).
+security:
+  - ApiKeyAuthHeader: []
+  - ApiKeyAuthQuery: []