lantern.yaml

---
openapi: 3.0.2
info:
  title: Lantern API
  version: 1.0.0
  description: Backend API for Lantern open source accounting software
  termsOfService: http://swagger.io/terms/
  contact:
    name: Lantern Team
    email: lanterndevelopers@gmail.com
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
paths:
  /api/accounts:
    summary: Path used to request accounts
    description: ""
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
          description: Successful response - returns an array of `Account` entities.
        "401":
          description: No ClientAuthToken provided
        "403":
          description: Invalid ClientAuthToken!
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
          description: Database/Plaid error
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
          description: No valid Plaid credentials in account! Cannot complete request.
      security:
      - clientToken: []
      operationId: getAccounts
      summary: GET /api/accounts
      description: Gets a list of all `Account` entities for user owning provided
        token
  /api/link:
    summary: For Plaid Link functionality
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaidLinkToken'
          description: Successfully created link token
        "401":
          description: No ClientAuthToken provided
        "403":
          description: ClientAuthToken invalid
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
          description: Database/Plaid error
      security:
      - clientToken: []
      operationId: createLinkToken
      summary: GET /api/link
      description: "The first step of linking a bank account.  Server will request\
        \ a link_token from Plaid /link/token/create endpoint, and return the temporary\
        \ token to the client."
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaidPublicToken'
        required: true
      responses:
        "200":
          description: Exchange successful
        "401":
          description: No ClientAuthToken provided
        "403":
          description: Invalid ClientAuthToken!
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
          description: Database/Plaid error
      security:
      - clientToken: []
      operationId: exchangePublicForItem
      summary: POST /api/link
      description: "Calls /item/public_token/exchange.  This returns an access token\
        \ and item ID.  Complete the rest of the fields in an Item, store it in the\
        \ database, then return a success code."
  /api/transactions:
    summary: Path used to request transactions
    description: ""
    get:
      parameters:
      - name: start_date
        description: "Number of transactions to offset by, for pagination purposes"
        schema:
          format: date
          type: string
        in: query
        required: false
      - name: end_date
        description: End date of transactions to fetch
        schema:
          format: date
          type: string
        in: query
      - name: offset
        description: Offset of transactions to fetch
        schema:
          type: integer
        in: query
        required: false
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionsResponse'
          description: Successful response - returns an array of `Transaction` entities.
        "401":
          description: ClientAuthToken not provided
        "403":
          description: ClientAuthToken invalid!
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
          description: Database/Plaid error!
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
          description: "No valid plaid items in user account, cannot make request!"
      security:
      - clientToken: []
      operationId: getTransactions
      summary: GET /api/transactions
      description: "Gets a list of all `Transaction` entities for user owning provided\
        \ token, as well as the number of total transactions to be fetched for query."
  /api/users/authenticate:
    summary: To authenticate (login) User client
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserAuthenticationInfo'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRegistrationRecord'
          description: "Successful login, client token"
        "401":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
              examples:
                invalid:
                  value: Invalid email or password!
          description: User authentication info is invalid
      operationId: authenticateClient
      summary: POST /api/users/authenticate
  /api/users/register:
    summary: For registration of new users (organizations)
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRegistrationInfo'
        required: true
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserRegistrationRecord'
          description: User account created
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Email already in use!
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
          description: Database record insertion error
      operationId: registerUser
      summary: POST /api/users/register
  /:
    summary: Generic test endpoint
    get:
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
          description: Get ok
  /api/users/update:
    summary: For updating user information
    post:
      requestBody:
        description: UserBio
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserBio'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
          description: Updated user
        "500":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
          description: Error
        "401":
          description: ClientAuthToken not provided
        "403":
          description: Invalid ClientAuthToken!
        "400":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
          description: Account invalid!
      security:
      - clientToken: []
      operationId: updateUserProfile
      summary: POST /api/users/update
components:
  schemas:
    User:
      description: User/Owner of organization
      required:
      - id
      - registration
      type: object
      properties:
        id:
          description: Unique ID of User
          type: integer
        registration:
          $ref: '#/components/schemas/UserRegistrationInfo'
          description: User registration info
    Error:
      required:
      - message
      type: object
      properties:
        message:
          description: Error message
          type: string
    Transaction:
      description: A financial transaction
      required:
      - name
      - accountID
      - date
      - amount
      - categories
      type: object
      properties:
        name:
          description: Descriptive name for the transaction
          type: string
        details:
          description: Additional description for the transaction
          type: string
        date:
          format: date
          description: Date transaction occurred
          type: string
        amount:
          description: Monetary amount of transaction (amount moved OUT of the account)
          type: number
        accountID:
          description: Plaid account ID of the account transaction is associated with
          type: string
        categories:
          description: Array of categories
          type: array
          items:
            type: string
    Institution:
      description: Represents a financial institution
      required:
      - id
      - name
      type: object
      properties:
        id:
          $ref: '#/components/schemas/InstitutionID'
          description: Plaid-provided institution id
        name:
          description: Name of financial institution
          type: string
    UserRegistrationInfo:
      description: Information required for User registration
      required:
      - auth
      - bio
      type: object
      properties:
        auth:
          $ref: '#/components/schemas/UserAuthenticationInfo'
          description: User authentication information
        bio:
          $ref: '#/components/schemas/UserBio'
          description: User biographic information
    UserAuthenticationInfo:
      description: Information used to authenticate users (login and signup)
      required:
      - email
      - password
      type: object
      properties:
        email:
          description: Email address of user
          pattern: "^(([^<>()\\[\\]\\\\.,;:\\s@\"]+(\\.[^<>()\\[\\]\\\\.,;:\\s@\"\
            ]+)*)|(\".+\"))@((\\[[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}\\.[0-9]{1,3}])|(([a-zA-Z\\\
            -0-9]+\\.)+[a-zA-Z]{2,}))$"
          type: string
        password:
          description: Password of user
          type: string
    UserBio:
      description: Biographic information about User
      required:
      - first
      - last
      - orgName
      type: object
      properties:
        first:
          description: First name of User
          type: string
        last:
          description: Last name of User
          type: string
        orgName:
          description: Name of User's organization
          type: string
    InstitutionID:
      description: Unique ID for a financial institution (provided by Plaid)
      pattern: "^ins_[0-9]+$"
      type: string
    Account:
      description: Financial account
      required:
      - name
      - id
      - balance
      - institution
      type: object
      properties:
        name:
          description: Name of account
          type: string
        description:
          description: Description of account
          type: string
        id:
          description: Unique Account ID (provided by Plaid)
          type: string
        balance:
          description: Current account balance
          type: number
        institution:
          $ref: '#/components/schemas/Institution'
          description: Financial institution account belongs to
    Token:
      description: Generic token type
      required:
      - token
      type: object
      properties:
        token:
          description: Token
          type: string
    PlaidItem:
      required:
      - id
      - institution
      - webhook
      - accessToken
      type: object
      properties:
        id:
          description: Unique Item ID (Assigned by Plaid)
          type: string
        institution:
          $ref: '#/components/schemas/Institution'
          description: Financial institution
        webhook:
          description: URL registered to receive webhooks for the item (Provided by
            Plaid)
          type: string
        accessToken:
          $ref: '#/components/schemas/PlaidAccessToken'
          description: Plaid access token for Item
    Message:
      description: Generic message
      required:
      - message
      type: object
      properties:
        message:
          description: Generic message string
          type: string
    UserPassHash:
      description: "Hash of user password, and some information about it"
      required:
      - salt
      - hash
      type: object
      properties:
        salt:
          description: Salt used when hashing original password
          type: string
        hash:
          description: Hashed password
          type: string
    PlaidLinkToken:
      oneOf:
      - $ref: '#/components/schemas/Token'
      description: Temporary link_token from Plaid
    ClientAuthToken:
      oneOf:
      - $ref: '#/components/schemas/Token'
      description: Token (or key) used by frontended to authenticate and authorize
        itself with the backend
    PlaidAccessToken:
      oneOf:
      - $ref: '#/components/schemas/Token'
      description: Plaid Access Token for a given Item
    PlaidPublicToken:
      oneOf:
      - $ref: '#/components/schemas/Token'
      description: "During Link process, Plaid public token is exchanged for a permanent\
        \ access token"
    UserRegistrationRecord:
      description: Data about a user registration event.  Returned by register endpoint.
      allOf:
      - required:
        - _id
        type: object
        properties:
          _id:
            description: Object insertion ID from MongoDB
            type: string
      - $ref: '#/components/schemas/ClientAuthToken'
    TransactionsResponse:
      description: Format of a response to a transactions request
      required:
      - transactions
      - total_transactions
      type: object
      properties:
        transactions:
          description: Array of transactions
          type: array
          items:
            $ref: '#/components/schemas/Transaction'
        total_transactions:
          description: Count of total transactions in specified date range (or last
            two years if no range specified)
          type: integer
  securitySchemes:
    clientToken:
      type: apiKey
      description: Client provides a token to the backend in order to authenticate
        and authorize itself
      name: Authorization
      in: header