# Copyright 2025 Ian Lewis
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

openapi: 3.0.4
info:
  title: fx.ianlewis.org
  description: A simple currency exchange rate API.
  version: v1

servers:
  - url: https://fx.ianlewis.org/v1
    description: The main production server.

components:
  schemas:
    Date:
      type: object
      properties:
        year:
          type: integer
        month:
          type: integer
        day:
          type: integer

    Money:
      type: object
      properties:
        currencyCode:
          type: string
          format: integer
        units:
          type: string
          format: integer
        nanos:
          type: integer

    Currency:
      type: object
      properties:
        alphabeticCode:
          type: string
        numericCode:
          type: string
          format: integer
        name:
          type: string
        minorUnits:
          type: integer
        countries:
          type: array
          items:
            type: string

    CurrencyList:
      type: object
      properties:
        currencies:
          type: array
          items:
            $ref: "#/components/schemas/Currency"

    Provider:
      type: object
      properties:
        name:
          type: string
        code:
          type: string

    ProviderList:
      type: object
      properties:
        providers:
          type: array
          items:
            $ref: "#/components/schemas/Provider"

    Quote:
      type: object
      properties:
        providerCode:
          type: string
        date:
          $ref: "#/components/schemas/Date"
        baseCurrencyCode:
          type: string
        quoteCurrencyCode:
          type: string
        ask:
          $ref: "#/components/schemas/Money"
        bid:
          $ref: "#/components/schemas/Money"
        mid:
          $ref: "#/components/schemas/Money"

    QuoteList:
      type: object
      properties:
        quotes:
          type: array
          items:
            $ref: "#/components/schemas/Quote"

paths:
  /currency.json:
    get:
      summary: Returns a list of currencies.
      description: Returns a full list of currencies. Not all providers support all currencies.
      responses:
        "200": # status code
          description: A Currency object.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Currency"

  /currency/{currency_code}.json:
    get:
      summary: Returns a currency.
      description: Returns a currency corresponding to `code`.
      parameters:
        - name: currency_code
          in: path
          required: true
          schema:
            type: string
          description: The ISO 4217 currency code.
      responses:
        "200": # status code
          description: A list of Currency objects.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CurrencyList"

  /provider.json:
    get:
      summary: Returns a list of providers.
      description: Returns a full list of supported currency conversion providers.
      responses:
        "200": # status code
          description: A list of Provider objects.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProviderList"

  /provider/{provider_code}.json:
    get:
      summary: Returns a provider.
      description: Returns a supported currency conversion provider.
      parameters:
        - name: provider_code
          in: path
          required: true
          schema:
            type: string
          description: The provider code.
      responses:
        "200": # status code
          description: A Provider object.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Provider"

  /provider/{provider_code}/quote/{base_currency_code}/{quote_currency_code}/{year}/{month}/{day}.json:
    get:
      summary: Returns a daily quote.
      description: Returns a daily currency conversion quote for the given provider.
      parameters:
        - name: provider_code
          in: path
          required: true
          schema:
            type: string
          description: The provider code.
        - name: base_currency_code
          in: path
          required: true
          schema:
            type: string
          description: The ISO 4217 currency code for the base currency.
        - name: quote_currency_code
          in: path
          required: true
          schema:
            type: string
          description: The ISO 4217 currency code for the quote currency.
        - name: year
          in: path
          required: true
          schema:
            type: string
            pattern: '^\d{4}$'
          description: Year in YYYY format
        - name: month
          in: path
          required: true
          schema:
            type: string
            pattern: '^\d{2}$'
          description: Month in MM format
        - name: day
          in: path
          required: true
          schema:
            type: string
            pattern: '^\d{2}$'
          description: Day in DD format
      responses:
        "200": # status code
          description: A Quote object.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Quote"

  /provider/{provider_code}/quote/{base_currency_code}/{quote_currency_code}/{year}/{month}.json:
    get:
      summary: Returns a list of quote for the month.
      description: Returns a list daily currency conversion quote for the provider in the given month.
      parameters:
        - name: provider_code
          in: path
          required: true
          schema:
            type: string
          description: The provider code.
        - name: base_currency_code
          in: path
          required: true
          schema:
            type: string
          description: The ISO 4217 currency code for the base currency.
        - name: quote_currency_code
          in: path
          required: true
          schema:
            type: string
          description: The ISO 4217 currency code for the quote currency.
        - name: year
          in: path
          required: true
          schema:
            type: string
            pattern: '^\d{4}$'
          description: Year in YYYY format
        - name: month
          in: path
          required: true
          schema:
            type: string
            pattern: '^\d{2}$'
          description: Month in MM format
      responses:
        "200": # status code
          description: A list of Quote objects.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuoteList"

  /provider/{provider_code}/quote/{base_currency_code}/{quote_currency_code}/{year}.json:
    get:
      summary: Returns a list of quote for the year.
      description: Returns a list daily currency conversion quote for the provider in the given year.
      parameters:
        - name: provider_code
          in: path
          required: true
          schema:
            type: string
          description: The provider code.
        - name: base_currency_code
          in: path
          required: true
          schema:
            type: string
          description: The ISO 4217 currency code for the base currency.
        - name: quote_currency_code
          in: path
          required: true
          schema:
            type: string
          description: The ISO 4217 currency code for the quote currency.
        - name: year
          in: path
          required: true
          schema:
            type: string
            pattern: '^\d{4}$'
          description: Year in YYYY format
      responses:
        "200": # status code
          description: A list of Quote objects.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QuoteList"
