ledger.yaml

swagger: '2.0'
info:
  title: Ledger API
  version: '2.0'
  description: Ledger API to view and manipulate Transaction related data.
basePath: /v2
schemes:
  - http
consumes:
  - application/json
produces:
  - application/json
paths:
  /health:
    get:
      summary: Health
      operationId: get_health
      responses:
        200:
          description: 'Success'
          schema:
            $ref: '#/definitions/health'
        400:
          $ref: '#/responses/invalid-request'
        404:
          $ref: '#/responses/not-found'
      tags:
        - health

  /api-docs:
    get:
      security: []
      summary: Get swagger documentation
      operationId: get_doc
      produces:
        - text/html
      responses:
        200:
          description: Success
      tags:
        - doc

  /balance/{entity_id}:
    get:
      summary: Get Balance
      operationId: get_balance
      consumes:
        - application/json
      parameters:
        - in: path
          name: entity_id
          description: UUID of the entity (User, Project, Organisation)
          type: string
          required: true
        - name: start_date
          in: query
          type: integer
          description: date-time in epoch (seconds)
          required: false
        - name: end_date
          in: query
          type: integer
          description: date-time in epoch (seconds)
          required: false
      responses:
        200:
          description: 'OK'
          schema:
            $ref: '#/definitions/balance'
        400:
          $ref: '#/responses/invalid-request'
        404:
          $ref: '#/responses/not-found'
      tags:
        - balance
        
  /transactions:
    get:
      summary: List Transactions
      operationId: list_transactions
      parameters:
        - $ref: '#/parameters/page_size'
        - $ref: '#/parameters/offset'
        - $ref: '#/parameters/order_by'
      responses:
        200:
          description: 'Success'
          schema:
            $ref: '#/definitions/transaction-list'
        400:
          $ref: '#/responses/invalid-request'
      tags:
        - transactions
    post:
      summary: Add a new Transaction
      operationId: create_transaction
      consumes:
        - application/json
      parameters:
        - in: body
          description: The transaction to create
          name: transaction
          required: true
          schema:
            $ref: '#/definitions/create-transaction'
      responses:
        201:
          description: 'Created'
          schema:
            $ref: '#/definitions/transaction'
        400:
          $ref: '#/responses/invalid-request'
        409:
          $ref: '#/responses/conflict'
      tags:
        - transactions
        
  /transactions/{transaction_id}:
    get:
      summary: Get Transaction
      operationId: getTransaction
      consumes:
        - application/json
      parameters:
        - in: path
          name: transaction_id
          type: string
          required: true
      responses:
        200:
          description: 'OK'
          schema:
            $ref: '#/definitions/transaction'
        400:
          $ref: '#/responses/invalid-request'
        404:
          $ref: '#/responses/not-found'
      tags:
        - transactions
        
responses:
  unauthorized:
    description: Unauthorized
    schema:
      $ref: '#/definitions/error-response'
  invalid-request:
    description: Invalid request
    schema:
      $ref: '#/definitions/error-response'
  forbidden:
    description: Insufficient privilege to execute action.
    schema:
      $ref: '#/definitions/error-response'
  not-found:
    description: Not found.
    schema:
      $ref: '#/definitions/error-response'
  conflict:
    description: Duplicate resource
    schema:
      $ref: '#/definitions/error-response'

definitions:
  health:
    type: object
    title: Health
    description: properties for Health
    properties:
      DateTime:
        type: string
        
  transaction-list:
    type: object
    x-nullable: false
    title: Transactions
    description: List of Transactions
    properties:
      total_size:
        type: integer
        x-omitempty: false
        format: int64
      page_size:
        type: integer
        x-omitempty: false
        format: int64
      offset:
        type: integer
        x-omitempty: false
        format: int64
      has_next:
        type: boolean
        x-omitempty: true
      Data:
        type: array
        items:
          $ref: '#/definitions/transaction'
          
  transaction:
    type: object
    properties:
      id:
        type: string
        description: UUID of the line_item.
        readOnly: true
        example: a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
      asset:
        type: string
        enum: [usd]
        example: usd
      account_id:
        type: string
        description: UUID of the associated account.
        example: c9e0e14a-17d2-4250-96d0-e95df41cc0c3
      running_balance:
        type: integer
        description: Sum of transactions for this account until this time in cents. This value can be + or -.
        example: 10000
      transaction_category:
        type: string
      external_transaction_id:
        type: string
        description: ID of this transaction from the external source
        example: txe0e14a-17d
        x-omitempty: false
      external_transaction_created_at:
        type: integer
        description: date-time in epoch (seconds)
        readOnly: true
        example: 1539815989
      metadata:
        type: string
        description: json formatted string holding dynamic data
      created_at:
        type: integer
        description: date-time in epoch (seconds)
        readOnly: true
        example: 1539815989
      external_created_at:
        type: integer
        description: date-time in epoch (seconds)
        readOnly: true
        example: 1539815989
      line_items:
        type: array
        items:
          $ref: '#/definitions/line-item'
        
  line-item:
    type: object
    properties:
      id:
        type: string
        description: UUID of the line_item.
        readOnly: true
        example: a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
      transaction_id:
        type: string
        description: UUID of the transaction.
        example: c9e0e14a-17d2-4250-96d0-e95df41cc0c3
      external_id:
        type: string
        description: ID of this line_item from the external source
        example: txe0e14a-17d
      description:
        type: string
        description: Description of the item.
        example: fee
        x-omitempty: false
      amount:
        type: integer
        description: Amount of transaction in cents. This value can be + or -.
        example: 10000
      metadata:
        type: string
        description: json formatted string holding dynamic data
      created_at:
        type: integer
        description: date-time in epoch (seconds)
        readOnly: true
        example: 1539815989
        
  create-transaction:
    type: object
    required:
      - entity_id
      - entity_type
      - external_source_type
      - external_account_id
      - external_transaction_id
      - line_items
    properties:
      entity_id:
        type: string
        description: UUID of the associated entity.
        example: c9e0e14a-17d2-4250-96d0-e95df41cc0c3
      entity_type:
        type: string
        enum: [user, project, organisation]
        example: user
      external_source_type:
        type: string
        enum: [bill.com, stripe, expensify]
        example: bill.com
      external_account_id:
        type: string
        description: ID of the external account
        example: stripe-17dabc
      asset:
        type: string
        enum: [usd]
        example: usd
      transaction_category:
        type: string
      external_transaction_id:
        type: string
        description: ID of this transaction from the external source
        example: txe0e14a-17d
      metadata:
        type: string
        description: json formatted string holding dynamic data
      line_items:
        type: array
        items:
          $ref: '#/definitions/create-line-item'
          
  create-line-item:
    type: object
    required:
      - amount
      - description
    properties:
      amount:
        type: integer
        description: Amount of transaction in cents. This value can be + or -.
        example: 10000
      description:
        type: string
        description: Description of the item.
        example: fee
      external_id:
        type: string
        description: ID of this line_item from the external source
        example: txe0e14a-17d
      metadata:
        type: string
        description: json formatted string holding dynamic data

  sub-category:
    type: object
    properties:
      name: 
        type: string
        description: Category name
        example: Lorem
      balance:
        type: integer
        description: Amount in cents.
        example: -66534
      count:
        type: integer
        description: Number of transactions in this category.
        example:
          min:
            value: 0
      credit:
        type: integer
        description: Total credit amount.
        example: 7
      credit_count:
        type: integer
        description: Number of credit transactions
        example:
          min:
            value: 0
      debit:
        type: integer
        description: Total debit amount.
        example: -454921
      debit_count:
        type: integer
        description: Number of debit transactions
        example:
          min:
            value: 0
            
  balance:
    type: object
    properties:
      entity_id:
        type: string
        description: UUID of the entity.
        example: c9e0e14a-17d2-4250-96d0-e95df41cc0c3
      entity_type:
        type: string
        enum: [user, project, organisation]
        example: project
      available_balance:
        type: integer
        description: Available balance for the project. total_credit - total_debit.
        example: 1488394
        x-omitempty: false
      total_count:
        type: integer
        description: Total transaction count.
        example:
          min:
            value: 0
        x-omitempty: false
      total_credit:
        type: integer
        description: Total credit to project.
        example: 2503428
        x-omitempty: false
      credit_count:
        type: integer
        description: Credit transaction count.
        example:
          min:
            value: 0
        x-omitempty: false
      total_debit:
        type: integer
        description: Total debit from project.
        example: -1000000
        x-omitempty: false
      debit_count:
        type: integer
        description: Debit transaction count.
        example:
          min:
            value: 0
        x-omitempty: false
      backers:
        type: integer
        description: Total backers for the project.
        example:
          min:
            value: 0
        x-omitempty: false
      sub_totals:
        type: array
        items:
          $ref: '#/definitions/sub-category'
        
  error-response:
    type: object
    title: Error Response
    description: Standard error format
    properties:
      Code:
        type: string
      Message:
        type: string
        
parameters:
  page_size:
    name: page_size
    in: query
    type: integer
    default: 10
    minimum: 1
    maximum: 100
  offset:
    name: offset
    in: query
    type: integer
    default: 0
  order_by:
    name: order_by
    in: query
    type: string
    default: 'createddate'
    pattern: '^[A-Za-z0-9_]+$'