swagger.yaml

swagger: '2.0'
info:
  version: '1.0.0'
  title: ViMbAdmin-API
  description: This is a quick and dirty Lumen base API for the ViMbAdmin database
  license:
    name: MIT
    url: http://opensource.org/licenses/MIT
host: vimbadmin-api.dev
schemes:
  - https
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  oAuthSecurity:
    type: oauth2
    tokenUrl: https://vimbadmin-api.dev/oauth/token
    flow: application
    scopes:
      default: Default
paths:
  /token:
    post:
      description: Request Auth token
      operationId: requestToken
      consumes:
        - application/x-www-form-urlencoded
      parameters:
        - name: client_id
          in: formData
          description: oAuth Client ID
          required: true
          type: string
        - name: client_type
          in: formData
          description: oAuth Client Secret
          required: true
          type: string
        - name: grant_type
          in: formData
          description: oAuth Grant Type
          required: true
          type: string
          enum: ['client_credentials']
      responses:
        '200':
          description: Bearer Token
          schema:
            $ref: '#/definitions/token'
        default:
          $ref: '#/responses/default'
  /domains:
    get:
      description: Returns all domains
      operationId: findDomains
      produces:
        - application/json
      security:
        - oAuthSecurity:
          - default
      parameters:
        - $ref: '#/parameters/q'
        - $ref: '#/parameters/include'
      responses:
        '200':
          description: domain response
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                 $ref: '#/definitions/domain'
              included:
                $ref: "#/definitions/included"
              links:
                 $ref: '#/definitions/link'
        '401':
          $ref: '#/responses/401'
        default:
          $ref: '#/responses/default'
  /domains/{id}:
    get:
      description: Return single domains
      operationId: getDomain
      produces:
        - application/json
      security:
        - oAuthSecurity:
          - default
      parameters:
        - $ref: '#/parameters/id'
        - $ref: '#/parameters/include'
      responses:
        '200':
          description: domain response
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                 $ref: '#/definitions/domain'
              included:
                $ref: "#/definitions/included"
              links:
                 $ref: '#/definitions/link'
        '401':
          $ref: '#/responses/401'
        '404':
          $ref: '#/responses/404'
        default:
          $ref: '#/responses/default'
  /{domainName}/mailboxes:
    get:
      description: Returns all mailboxes for given domain
      operationId: findMailboxesForDoman
      produces:
        - application/json
      security:
        - oAuthSecurity:
          - default
      parameters:
        - $ref: '#/parameters/domainName'
      responses:
        '200':
          description: domain mailboxes response
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/definitions/mailbox'
              included:
                $ref: "#/definitions/included"
              links:
                $ref: '#/definitions/link'
        '401':
          $ref: '#/responses/401'
        default:
          $ref: '#/responses/default'
  /{domainName}/mailboxes/{id}:
    get:
      description: Return a mailbox for given domain
      operationId: getMailboxForDomain
      produces:
        - application/json
      security:
        - oAuthSecurity:
          - default
      parameters:
        - $ref: '#/parameters/domainName'
        - $ref: '#/parameters/id'
      responses:
        '200':
          description: domain mailboxes response
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/definitions/mailbox'
              included:
                $ref: "#/definitions/included"
              links:
                $ref: '#/definitions/link'
        '401':
          $ref: '#/responses/401'
        '404':
          $ref: '#/responses/404'
        default:
          $ref: '#/responses/default'
    patch:
      description: Update a mailbox
      operationId: updateMailbox
      produces:
        - application/json
      security:
        - oAuthSecurity:
          - default
      parameters:
        - $ref: '#/parameters/domainName'
        - $ref: '#/parameters/id'
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/mailbox'
      responses:
        '200':
          description: mailbox updated response
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/definitions/mailbox'
              included:
                $ref: "#/definitions/included"
              links:
                $ref: '#/definitions/link'
        '401':
          $ref: '#/responses/401'
        '409':
          $ref: '#/responses/409'
        default:
          $ref: '#/responses/default'
  /{domainName}/aliases:
    get:
      description: Returns all aliases for given domain
      operationId: findAliasesForDomain
      produces:
        - application/json
      security:
        - oAuthSecurity:
          - default
      parameters:
        - $ref: '#/parameters/domainName'
      responses:
        '200':
          description: domain alises response
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/definitions/alias'
              included:
                $ref: "#/definitions/included"
              links:
                $ref: '#/definitions/link'
        '401':
          $ref: '#/responses/401'
        default:
          $ref: '#/responses/default'
    post:
      description: Create a new alias
      operationId: createAlias
      produces:
        - application/json
      security:
        - oAuthSecurity:
          - default
      parameters:
        - $ref: '#/parameters/domainName'
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/mailbox'
      responses:
        '201':
          description: alias created response
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/definitions/alias'
              included:
                $ref: "#/definitions/included"
              links:
                $ref: '#/definitions/link'
        '401':
          $ref: '#/responses/401'
        '409':
          $ref: '#/responses/409'
        default:
          $ref: '#/responses/default'
  /{domainName}/aliases/{id}:
    get:
      description: Return a alias for given domain
      operationId: getAliasForDomain
      produces:
        - application/json
      security:
        - oAuthSecurity:
          - default
      parameters:
        - $ref: '#/parameters/domainName'
        - $ref: '#/parameters/id'
      responses:
        '200':
          description: domain alias response
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/definitions/alias'
              included:
                $ref: "#/definitions/included"
              links:
                $ref: '#/definitions/link'
        '401':
          $ref: '#/responses/401'
        '404':
          $ref: '#/responses/404'
        default:
          $ref: '#/responses/default'
    patch:
      description: Update a alias
      operationId: updateAlias
      produces:
        - application/json
      security:
        - oAuthSecurity:
          - default
      parameters:
        - $ref: '#/parameters/domainName'
        - $ref: '#/parameters/id'
        - name: body
          in: body
          required: true
          schema:
            $ref: '#/definitions/mailbox'
      responses:
        '200':
          description: aliase updated response
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/definitions/alias'
              included:
                $ref: "#/definitions/included"
              links:
                $ref: '#/definitions/link'
        '401':
          $ref: '#/responses/401'
        '409':
          $ref: '#/responses/409'
        default:
          $ref: '#/responses/default'
parameters:
  domainName:
    name: domainName
    in: path
    description: Domain Name
    required: true
    type: string
  id:
    name: id
    in: path
    description: id
    required: true
    type: string
  q:
    name: q
    in: query
    description: search query
    required: false
    type: string
  include:
    name: include
    in: query
    description: additional relations to include in the response
    required: false
    type: array
    items:
      enum: ['mailboxes', 'aliases']
    uniqueItems: true
    collectionFormat: csv
responses:
  401:
    description: Unauthorized
    schema:
      type: object
      required:
        - errors
      properties:
        errors:
          $ref: '#/definitions/error'
        links:
          $ref: '#/definitions/link'
  404:
    description: Not Found
    schema:
      type: object
      required:
        - errors
      properties:
        errors:
          $ref: '#/definitions/error'
        links:
          $ref: '#/definitions/link'
  409:
    description: Conflict
    schema:
      type: object
      required:
        - errors
      properties:
        errors:
          $ref: '#/definitions/error'
        links:
          $ref: '#/definitions/link'
  default:
    description: unexpected error
    schema:
      type: object
      required:
        - errors
      properties:
        errors:
          $ref: '#/definitions/error'
        links:
          $ref: '#/definitions/link'
definitions:
  domain:
    type: object
    required:
      - id
      - type
    properties:
      id:
        type: integer
        format: int64
      type:
        type: string
      attributes:
        type: object
        properties:
          domain:
            type: string
      links:
        $ref: '#/definitions/link'
      relationships:
        $ref: "#/definitions/relationships"
  mailbox:
    type: object
    required:
      - id
      - type
    properties:
      id:
        type: integer
        format: int64
      type:
        type: string
      attributes:
        type: object
        properties:
          username:
            type: string
          name:
            type: string
      links:
        $ref: '#/definitions/link'
      relationships:
        $ref: "#/definitions/relationships"
  alias:
    type: object
    required:
      - id
      - type
    properties:
      id:
        type: integer
        format: int64
      type:
        type: string
      attributes:
        type: object
        properties:
          address:
            type: string
          goto:
            type: array
            items:
              type: string
      links:
        $ref: '#/definitions/link'
      relationships:
        $ref: "#/definitions/relationships"
  relationships:
    type: object
    properties:
      domains:
        $ref: "#/definitions/relation"
      aliases:
        $ref: "#/definitions/relation"
      mailboxes:
        $ref: "#/definitions/relation"
  relation:
    type: object
    properties:
      links:
        $ref: "#/definitions/link"
      data:
        type: array
        items:
          type: object
          required:
            - id
            - type
          properties:
            id:
              type: integer
              format: int64
            type:
              type: string
  included:
    type: array
    items:
      type: object
      required:
        - id
        - type
      properties:
        id:
          type: integer
          format: int64
        type:
          type: string
        attributes:
          type: object
        links:
          $ref: '#/definitions/link'
  link:
    type: object
    properties:
      self:
        type: string
      related:
        type: string
  error:
    type: object
    required:
      - status
      - title
      - detail
    properties:
      status:
        type: integer
      title:
        type: string
      detail:
        type: string
      meta:
        type: object
  token:
    type: object
    required:
      - token_type
      - expires_in
      - access_token
    properties:
      token_type:
        type: string
      expires_in:
        type: integer
      access_token:
        type: string