swagger.yml

swagger: "2.0"
info:
  title: TRMAPI
  description: |
    JSON API para consultar la [Tasa Representativa del Mercado](http://www.banrep.gov.co/es/tasa-cambio-del-peso-colombiano-trm) (TRM) en el [Servicio Web](https://www.superfinanciera.gov.co/inicio/60819) de la Superintendencia Financiera de Colombia (SFC).

    Esta API es una función Lambda que se ejecuta en AWS y a la cual se accede por API Gateway, lo que garantiza su estabilidad, escalabilidad y rapidez.

    La función lambda solicita la información al servicio web de la SFC y almacena el valor de la TRM en una tabla de Dynamodb.

    Al usar esta API se reduce la carga sobre los servidores de la SFC y se garantiza la disponibilidad del servicio.
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://www.trmapi.com/terminos/
  contact:
    name: trmapi
    url: https://www.trmapi.com
    email: info@trmapi.com

host: api.trmapi.com
basePath: /
schemes:
  - https

paths:
  /latest:
    get:
      summary: Latest Endpoint
      description: Responde con el valor de la TRM que aplica para la fecha actual. Si para la fecha actual no hay valor de la TRM se devuelte el valor más reciente.
      produces:
        - application/json
      parameters:
        - $ref: "#/parameters/validity"
      responses:
        200:
          description: Ok
          schema:
            $ref: "#/definitions/TRM"
        404:
          description: No se encontró la fecha solicitada
        422:
          description: La fecha solicitada no es una fecha válida
        502:
          description: Se ha recibido una respuesta inválida del servidor de la SFC
        504:
          description: Se agotó el tiempo de respuesta para el servidor de la SFC
        default:
          description: Error inesperado
          schema:
            $ref: "#/definitions/Error"
  /{date}:
    get:
      summary: Historical Endpoint
      description: Devuelve el valor de la TRM que aplica para la fecha solicitada, la cual se debe ingresar en formato `YYYY-MM-DD`.
      produces:
        - application/json
      parameters:
        - $ref: "#/parameters/validity"
        - name: date
          in: path
          description: Una fecha del pasado para la cual se desea consultar el valor de la TRM. La fecha se debe ingresar en formato `YYYY-MM-DD`
          required: true
          type: string
      responses:
        200:
          description: Ok
          schema:
            $ref: "#/definitions/TRM"
        404:
          description: No se encontró la fecha solicitada
        422:
          description: La fecha solicitada no es una fecha válida
        502:
          description: Se ha recibido una respuesta inválida del servidor de la SFC
        504:
          description: Se agotó el tiempo de respuesta para el servidor de la SFC
        default:
          description: Error inesperado
          schema:
            $ref: "#/definitions/Error"
  /timeseries:
    get:
      summary: Time-Series Endpoint
      description: Responde con los valores diarios de la TRM que aplican entre dos fechas. El número máximo de días que se puede solicitar es de 365.
      produces:
        - application/json
      parameters:
        - $ref: "#/parameters/validity"
        - name: start_date
          in: query
          description: La fecha inicial del intervalo de tiempo que se desea consultar en formato `YYYY-MM-DD`.
          required: true
          type: string
        - name: end_date
          in: query
          description: La fecha final del intervalo de tiempo que se desea consultar en formato `YYYY-MM-DD`.
          required: true
          type: string
      responses:
        200:
          description: Ok
          schema:
            $ref: "#/definitions/Time-Series"
        404:
          description: No se encontró la fecha solicitada
        422:
          description: La fecha solicitada no es una fecha válida
        502:
          description: Se ha recibido una respuesta inválida del servidor de la SFC
        504:
          description: Se agotó el tiempo de respuesta para el servidor de la SFC
        default:
          description: Error inesperado
          schema:
            $ref: "#/definitions/Error"

parameters:
  validity:
    name: validity
    description: Indica si se muestra las fechas para las que son válidas un valor.
    type: boolean
    in: query
    required: false
    default: false

definitions:
  TRM:
    type: object
    title: Tasa Representativa del Mercado
    required:
      - date
      - value
    properties:
      date:
        type: string
        title: Fecha para la cual se realizó la solicitud
        example: "2018-10-10"
      value:
        type: number
        title: El valor correspondiente a la TRM
        example: 3057.55
  Time-Series:
    type: array
    title: Histórico Tasa Representativa del Mercado
    items:
      $ref: "#/definitions/TRM"
  Error:
    type: object
    required:
      - error
    properties:
      error:
        type: string
        title: El mensaje del error encontrado
        example: "La fecha solicitada no corresponde con el formato YYYY-MM-DD"