zrok/specs/zrok.yml

info:
  description: zrok client access
  title: zrok
  version: 0.3.0

basePath: /api/v1

securityDefinitions:
  key:
    type: apiKey
    in: header
    name: x-token

paths:
  #
  # account
  #
  /invite:
    post:
      tags:
        - account
      operationId: invite
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/inviteRequest"
      responses:
        201:
          description: invitation created
        400:
          description: invitation not created (already exists)
        500:
          description: internal server error

  /login:
    post:
      tags:
        - account
      operationId: login
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/loginRequest"
      responses:
        200:
          description: login successful
          schema:
            $ref: "#/definitions/loginResponse"
        401:
          description: invalid login

  /register:
    post:
      tags:
        - account
      operationId: register
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/registerRequest"
      responses:
        200:
          description: account created
          schema:
            $ref: "#/definitions/registerResponse"
        404:
          description: request not found
        500:
          description: internal server error

  /verify:
    post:
      tags:
        - account
      operationId: verify
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/verifyRequest"
      responses:
        200:
          description: token ready
          schema:
            $ref: "#/definitions/verifyResponse"
        404:
          description: token not found
        500:
          description: internal server error

  #
  # admin
  #
  /frontend:
    post:
      tags:
        - admin
      security:
        - key: []
      operationId: createFrontend
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/createFrontendRequest"
      responses:
        201:
          description: frontend created
          schema:
            $ref: "#/definitions/createFrontendResponse"
        401:
          description: unauthorized
        404:
          description: not found
        500:
          description: internal server error
    patch:
      tags:
        - admin
      security:
        - key: []
      operationId: updateFrontend
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/updateFrontendRequest"
      responses:
        200:
          description: frontend updated
        401:
          description: unauthorized
        404:
          description: not found
        500:
          description: internal server error
    delete:
      tags:
        - admin
      security:
        - key: []
      operationId: deleteFrontend
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/deleteFrontendRequest"
      responses:
        200:
          description: frontend deleted
        401:
          description: unauthorized
        404:
          description: not found
        500:
          description: internal server error

  /frontends:
    get:
      tags:
        - admin
      security:
        - key: []
      operationId: listFrontends
      responses:
        200:
          description: ok
          schema:
            $ref: "#/definitions/publicFrontendList"
        401:
          description: unauthorized
        500:
          description: internal server error

  /identity:
    post:
      tags:
        - admin
      security:
        - key: []
      operationId: createIdentity
      parameters:
        - name: body
          in: body
          schema:
            properties:
              name:
                type: string
      responses:
        201:
          description: created
          schema:
            properties:
              identity:
                type: string
              cfg:
                type: string
        401:
          description: unauthorized
        500:
          description: internal server error
  #
  # environment
  #
  /enable:
    post:
      tags:
        - environment
      security:
        - key: []
      operationId: enable
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/enableRequest"
      responses:
        201:
          description: environment enabled
          schema:
            $ref: "#/definitions/enableResponse"
        401:
          description: unauthorized
        404:
          description: account not found
        500:
          description: internal server error

  /disable:
    post:
      tags:
        - environment
      security:
        - key: []
      operationId: disable
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/disableRequest"
      responses:
        200:
          description: environment disabled
        401:
          description: invalid environment
        500:
          description: internal server error

  #
  # metadata
  #
  /detail/environment/{envZId}:
    get:
      tags:
        - metadata
      security:
        - key: []
      operationId: getEnvironmentDetail
      parameters:
        - name: envZId
          in: path
          type: string
          required: true
      responses:
        200:
          description: ok
          schema:
            $ref: "#/definitions/environmentServices"
        401:
          description: unauthorized
        404:
          description: not found
        500:
          description: internal server error

  /detail/service/{svcToken}:
    get:
      tags:
        - metadata
      security:
        - key: []
      operationId: getServiceDetail
      parameters:
        - name: svcToken
          in: path
          type: string
          required: true
      responses:
        200:
          description: ok
          schema:
            $ref: "#/definitions/service"
        401:
          description: unauthorized
        404:
          description: not found
        500:
          description: internal server error

  /overview:
    get:
      tags:
        - metadata
      security:
        - key: []
      operationId: overview
      responses:
        200:
          description: overview returned
          schema:
            $ref: "#/definitions/environmentServicesList"
        500:
          description: internal server error
          schema:
            $ref: "#/definitions/errorMessage"

  /version:
    get:
      tags:
        - metadata
      operationId: version
      responses:
        200:
          description: current server version
          schema:
            $ref: "#/definitions/version"
  #
  # service
  #
  /access:
    post:
      tags:
        - service
      security:
        - key: []
      operationId: access
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/accessRequest"
      responses:
        201:
          description: access created
          schema:
            $ref: "#/definitions/accessResponse"
        401:
          description: unauthorized
        404:
          description: not found
        500:
          description: internal server error

  /service:
    get:
      tags:
        - service
      security:
        - key: []
      operationId: getService
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/serviceRequest"
      responses:
        200:
          description: ok
          schema:
            $ref: "#/definitions/service"
        401:
          description: unauthorized
        404:
          description: not found
        500:
          description: internal server error

  /share:
    post:
      tags:
        - service
      security:
        - key: []
      operationId: share
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/shareRequest"
      responses:
        201:
          description: service created
          schema:
            $ref: "#/definitions/shareResponse"
        401:
          description: unauthorized
        404:
          description: not found
        500:
          description: internal server error
          schema:
            $ref: "#/definitions/errorMessage"
    patch:
      tags:
        - service
      security:
        - key: []
      operationId: updateShare
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/updateShareRequest"
      responses:
        200:
          description: service updated
        401:
          description: unauthorized
        404:
          description: not found
        500:
          description: internal server error

  /unaccess:
    delete:
      tags:
        - service
      security:
        - key: []
      operationId: unaccess
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/unaccessRequest"
      responses:
        200:
          description: access removed
        401:
          description: unauthorized
        404:
          description: not found
        500:
          description: internal server error

  /unshare:
    delete:
      tags:
        - service
      security:
        - key: []
      operationId: unshare
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/unshareRequest"
      responses:
        200:
          description: service removed
        401:
          description: unauthorized
        404:
          description: not found
        500:
          description: internal server error
          schema:
            $ref: "#/definitions/errorMessage"

definitions:
  accessRequest:
    type: object
    properties:
      envZId:
        type: string
      svcToken:
        type: string

  accessResponse:
    type: object
    properties:
      frontendToken:
        type: string

  authUser:
    type: object
    properties:
      username:
        type: string
      password:
        type: string

  createFrontendRequest:
    type: object
    properties:
      zId:
        type: string
      url_template:
        type: string
      public_name:
        type: string

  createFrontendResponse:
    type: object
    properties:
      token:
        type: string

  deleteFrontendRequest:
    type: object
    properties:
      frontendToken:
        type: string

  disableRequest:
    type: object
    properties:
      identity:
        type: string

  enableRequest:
    type: object
    properties:
      description:
        type: string
      host:
        type: string

  enableResponse:
    type: object
    properties:
      identity:
        type: string
      cfg:
        type: string

  environment:
    type: object
    properties:
      description:
        type: string
      host:
        type: string
      address:
        type: string
      zId:
        type: string
      active:
        type: boolean
      createdAt:
        type: integer
      updatedAt:
        type: integer

  environments:
    type: array
    items:
      $ref: "#/definitions/environment"

  environmentServicesList:
    type: array
    items:
      $ref: "#/definitions/environmentServices"

  environmentServices:
    type: object
    properties:
      environment:
        $ref: "#/definitions/environment"
      services:
        $ref: "#/definitions/services"

  errorMessage:
    type: string

  inviteRequest:
    type: object
    properties:
      email:
        type: string

  loginRequest:
    type: object
    properties:
      email:
        type: string
      password:
        type: string

  loginResponse:
    type: string

  principal:
    type: object
    properties:
      id:
        type: integer
      email:
        type: string
      token:
        type: string
      admin:
        type: boolean

  publicFrontend:
    type: object
    properties:
      token:
        type: string
      zId:
        type: string
      urlTemplate:
        type: string
      publicName:
        type: string
      createdAt:
        type: integer
      updatedAt:
        type: integer

  publicFrontendList:
    type: array
    items:
      $ref: "#/definitions/publicFrontend"

  registerRequest:
    type: object
    properties:
      token:
        type: string
      password:
        type: string

  registerResponse:
    type: object
    properties:
      token:
        type: string

  service:
    type: object
    properties:
      token:
        type: string
      zId:
        type: string
      shareMode:
        type: string
      backendMode:
        type: string
      frontendSelection:
        type: string
      frontendEndpoint:
        type: string
      backendProxyEndpoint:
        type: string
      reserved:
        type: boolean
      metrics:
        $ref: "#/definitions/serviceMetrics"
      createdAt:
        type: integer
      updatedAt:
        type: integer

  services:
    type: array
    items:
      $ref: "#/definitions/service"

  serviceMetrics:
    type: array
    items:
      type: integer

  serviceRequest:
    type: object
    properties:
      envZId:
        type: string
      svcToken:
        type: string

  shareRequest:
    type: object
    properties:
      envZId:
        type: string
      shareMode:
        type: string
        enum: ["public", "private"]
      frontendSelection:
        type: array
        items:
          type: string
      backendMode:
        type: string
        enum: ["proxy", "web", "dav"]
      backendProxyEndpoint:
        type: string
      authScheme:
        type: string
      authUsers:
        type: array
        items:
          $ref: "#/definitions/authUser"
      reserved:
        type: boolean

  shareResponse:
    type: object
    properties:
      frontendProxyEndpoints:
        type: array
        items:
          type: string
      svcToken:
        type: string

  unaccessRequest:
    type: object
    properties:
      frontendToken:
        type: string
      envZId:
        type: string
      svcToken:
        type: string

  unshareRequest:
    type: object
    properties:
      envZId:
        type: string
      svcToken:
        type: string
      reserved:
        type: boolean

  updateFrontendRequest:
    type: object
    properties:
      frontendToken:
        type: string
      publicName:
        type: string
      urlTemplate:
        type: string

  updateShareRequest:
    type: object
    properties:
      serviceToken:
        type: string
      backendProxyEndpoint:
        type: string

  verifyRequest:
    type: object
    properties:
      token:
        type: string
  verifyResponse:
    type: object
    properties:
      email:
        type: string

  version:
    type: string

produces:
- application/zrok.v1+json
consumes:
- application/zrok.v1+json
schemes:
- http
swagger: "2.0"