foodsoft/doc/swagger.v1.yml

swagger: '2.0'
info:
  title: Foodsoft API v1
  version: '1.0.0'
  description: >
    [Foodsoft](https://github.com/foodcoops/foodsoft) is web-based software to manage
    a non-profit food coop (product catalog, ordering, accounting, job scheduling).


    This is a description of Foodsoft's API v1.


    Note that each food cooperative typically has their own instance (on a shared
    server or their own installation), and there are just as many APIs (if the Foodsoft
    version is recent enough).
    This API description points to the default development url with the default
    Foodsoft scope - that would be [http://localhost:3000/f](http://localhost:3000/f).

    You may find the search parameters for index endpoints lacking. They are not
    documented here, because there are too many combinations. For now, you'll need
    to resort to [Ransack](https://github.com/activerecord-hackery/ransack) and
    looking at Foodsoft's `ransackable_*` model class methods.
externalDocs:
  description: General Foodsoft API documentation
  url: https://github.com/foodcoops/foodsoft/blob/master/doc/API.md

# development url with default scope
host: localhost:3000
schemes:
  - 'http'
basePath: /f/api/v1

produces:
  - 'application/json'

paths:
  /user:
    get:
      summary: info about the currently logged-in user
      tags:
        - 1. User
      responses:
        200:
          description: success
          schema:
            type: object
            properties:
              user:
                $ref: '#/definitions/User'
        401:
          description: not logged-in
          schema:
            $ref: '#/definitions/Error401'
        403:
          description: missing scope
          schema:
            $ref: '#/definitions/Error403'
      security:
        - foodsoft_auth: ['user:read', 'user:write']

  /user/financial_transactions:
    get:
      summary: financial transactions of the member's ordergroup
      tags:
        - 1. User
        - 6. FinancialTransaction
      parameters:
        - $ref: '#/parameters/page'
        - $ref: '#/parameters/per_page'
      responses:
        200:
          description: success
          schema:
            type: object
            properties:
              financial_transactions:
                type: array
                items:
                  $ref: '#/definitions/FinancialTransaction'
              meta:
                $ref: '#/definitions/Meta'
        401:
          description: not logged-in
          schema:
            $ref: '#/definitions/Error401'
        403:
          description: user has no ordergroup or missing scope
          schema:
            $ref: '#/definitions/Error403'
      security:
        - foodsoft_auth: ['finance:user']
  /user/financial_transactions/{id}:
    parameters:
      - $ref: '#/parameters/idInUrl'
    get:
      summary: find financial transaction by id
      tags:
        - 1. User
        - 6. FinancialTransaction
      responses:
        200:
          description: success
          schema:
            type: object
            properties:
              financial_transaction:
                $ref: '#/definitions/FinancialTransaction'
        401:
          description: not logged-in
          schema:
            $ref: '#/definitions/Error401'
        403:
          description: user has no ordergroup or missing scope
          schema:
            $ref: '#/definitions/Error403'
        404:
          description: not found
          schema:
            $ref: '#/definitions/Error404'
      security:
        - foodsoft_auth: ['finance:user']

  /financial_transactions:
    get:
      summary: financial transactions
      tags:
        - 6. FinancialTransaction
      parameters:
        - $ref: '#/parameters/page'
        - $ref: '#/parameters/per_page'
      responses:
        200:
          description: success
          schema:
            type: object
            properties:
              financial_transactions:
                type: array
                items:
                  $ref: '#/definitions/FinancialTransaction'
              meta:
                $ref: '#/definitions/Meta'
        401:
          description: not logged-in
          schema:
            $ref: '#/definitions/Error401'
        403:
          description: missing scope or no permission
          schema:
            $ref: '#/definitions/Error403'
      security:
        - foodsoft_auth: ['finance:read', 'finance:write']
  /financial_transactions/{id}:
    parameters:
      - $ref: '#/parameters/idInUrl'
    get:
      summary: find financial transaction by id
      tags:
        - 6. FinancialTransaction
      responses:
        200:
          description: success
          schema:
            type: object
            properties:
              financial_transaction:
                $ref: '#/definitions/FinancialTransaction'
        401:
          description: not logged-in
          schema:
            $ref: '#/definitions/Error401'
        403:
          description: missing scope or no permission
          schema:
            $ref: '#/definitions/Error403'
        404:
          description: not found
          schema:
            $ref: '#/definitions/Error404'
      security:
        - foodsoft_auth: ['finance:read', 'finance:write']

  /financial_transaction_classes:
    get:
      summary: financial transaction classes
      tags:
        - 2. Category
      parameters:
        - $ref: '#/parameters/page'
        - $ref: '#/parameters/per_page'
      responses:
        200:
          description: success
          schema:
            type: object
            properties:
              financial_transaction_classes:
                type: array
                items:
                  $ref: '#/definitions/FinancialTransactionClass'
              meta:
                $ref: '#/definitions/Meta'
        401:
          description: not logged-in
          schema:
            $ref: '#/definitions/Error401'

      security:
        - foodsoft_auth: ['all']
  /financial_transaction_classes/{id}:
    parameters:
      - $ref: '#/parameters/idInUrl'
    get:
      summary: find financial transaction class by id
      tags:
        - 2. Category
      responses:
        200:
          description: success
          schema:
            type: object
            properties:
              financial_transaction_class:
                $ref: '#/definitions/FinancialTransactionClass'
        401:
          description: not logged-in
          schema:
            $ref: '#/definitions/Error401'
        404:
          description: not found
          schema:
            $ref: '#/definitions/Error404'
      security:
        - foodsoft_auth: ['all']

  /financial_transaction_types:
    get:
      summary: financial transaction types
      tags:
        - 2. Category
      parameters:
        - $ref: '#/parameters/page'
        - $ref: '#/parameters/per_page'
      responses:
        200:
          description: success
          schema:
            type: object
            properties:
              financial_transaction_types:
                type: array
                items:
                  $ref: '#/definitions/FinancialTransactionType'
              meta:
                $ref: '#/definitions/Meta'
        401:
          description: not logged-in
          schema:
            $ref: '#/definitions/Error401'

      security:
        - foodsoft_auth: ['all']
  /financial_transaction_types/{id}:
    parameters:
      - $ref: '#/parameters/idInUrl'
    get:
      summary: find financial transaction type by id
      tags:
        - 2. Category
      responses:
        200:
          description: success
          schema:
            type: object
            properties:
              financial_transaction_type:
                $ref: '#/definitions/FinancialTransactionType'
        401:
          description: not logged-in
          schema:
            $ref: '#/definitions/Error401'
        404:
          description: not found
          schema:
            $ref: '#/definitions/Error404'
      security:
        - foodsoft_auth: ['all']

  /config:
    get:
      summary: configuration variables
      tags:
        - 7. General
      responses:
        200:
          description: success
          schema:
            type: object
        401:
          description: not logged-in
          schema:
            $ref: '#/definitions/Error401'
        403:
          description: missing scope or no permission
          schema:
            $ref: '#/definitions/Error403'
      security:
        - foodsoft_auth: ['config:user', 'config:read', 'config:write']
  /navigation:
    get:
      summary: navigation
      tags:
        - 7. General
      responses:
        200:
          description: success
          schema:
            type: object
            properties:
              navigation:
                $ref: '#/definitions/Navigation'
        401:
          description: not logged-in
          schema:
            $ref: '#/definitions/Error401'
      security:
        - foodsoft_auth: []

parameters:
  # url parameters
  idInUrl:
    name: id
    type: integer
    in: path
    minimum: 1
    required: true

  # query parameters
  page:
    name: page
    type: integer
    in: query
    description: page number
    minimum: 0
    default: 0
  per_page:
    name: per_page
    type: integer
    in: query
    description: items per page
    minimum: 0
    default: 20

definitions:
  # models
  User:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
        description: full name
      email:
        type: string
        description: email address
      locale:
        type: string
        description: language code
    required: ['id', 'name', 'email']

  FinancialTransaction:
    type: object
    properties:
      id:
        type: integer
      user_id:
        type: ['integer', 'null']
        description: id of user who entered the transaction (may be <tt>null</tt> for deleted users or 0 for a system user)
      user_name:
        type: ['string', 'null']
        description: name of user who entered the transaction (may be <tt>null</tt> or empty string for deleted users or system users)
      amount:
        type: number
        description: amount credited (negative for a debit transaction)
      financial_transaction_type_id:
        type: integer
        description: id of the type of the transaction
      financial_transaction_type_name:
        type: string
        description: name of the type of the transaction
      note:
        type: string
        description: note entered with the transaction
      created_at:
        type: string
        format: date-time
        description: when the transaction was entered
    required: ['id', 'user_id', 'user_name', 'amount', 'financial_transaction_type_id', 'financial_transaction_type_name', 'note', 'created_at']

  FinancialTransactionClass:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
        description: full name
    required: ['id', 'name']

  FinancialTransactionType:
    type: object
    properties:
      id:
        type: integer
      name:
        type: string
        description: full name
      name_short:
        type: ['string', 'null']
        description: short name (used for bank transfers)
      bank_account_id:
        type: ['integer', 'null']
        description: id of the bank account used for this transaction type
      bank_account_name:
        type: ['string', 'null']
        description: name of the bank account used for this transaction type
      bank_account_iban:
        type: ['string', 'null']
        description: IBAN of the bank account used for this transaction type
      financial_transaction_class_id:
        type: integer
        description: id of the class of the transaction
      financial_transaction_class_name:
        type: string
        description: name of the class of the transaction
    required: ['id', 'name', 'financial_transaction_class_id', 'financial_transaction_class_name']

  Navigation:
    type: array
    items:
      type: object
      properties:
        name:
          type: string
          description: title
        url:
          type: string
          description: link
        items:
          $ref: '#/definitions/Navigation'
      required: ['name']
      minProperties: 2 # name+url or name+items

  # collection meta object in root of a response
  Meta:
    type: object
    properties:
      page:
        type: integer
        description: page number of the returned collection
      per_page:
        type: integer
        description: number of items per page
      total_pages:
        type: integer
        description: total number of pages
      total_count:
        type: integer
        description: total number of items in the collection
    required: ['page', 'per_page', 'total_pages', 'total_count']

  Error:
    type: object
    properties:
      error:
        type: string
        description: error code
      error_description:
        type: string
        description: human-readable error message (localized)
  Error404:
    type: object
    properties:
      error:
        type: string
        description: '<tt>not_found</tt>'
      error_description:
        $ref: '#/definitions/Error/properties/error_description'
  Error401:
    type: object
    properties:
      error:
        type: string
        description: '<tt>unauthorized</tt>'
      error_description:
        $ref: '#/definitions/Error/properties/error_description'
  Error403:
    type: object
    properties:
      error:
        type: string
        description: '<tt>forbidden</tt> or <tt>invalid_scope</tt>'
      error_description:
        $ref: '#/definitions/Error/properties/error_description'

securityDefinitions:
  foodsoft_auth:
    type: oauth2
    flow: implicit
    authorizationUrl: http://localhost:3000/f/oauth/authorize
    scopes:
      config:user: reading Foodsoft configuration for regular users
      config:read: reading Foodsoft configuration values
      config:write: reading and updating Foodsoft configuration values
      finance:user: accessing your own financial transactions
      finance:read: reading all financial transactions
      finance:write: reading and creating financial transactions
      user:read: reading your own user profile
      user:write: reading and updating your own user profile
      offline_access: retain access after user has logged out