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
  #
  /forgotPassword:
    post:
      tags:
        - account
      operationId: forgotPassword
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/forgotPasswordRequest"
      responses:
        201:
          description: forgot password request created
        500:
          description: internal server error

  /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

  /resetPassword:
    post:
      tags:
        - account
      operationId: resetPassword
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/resetPasswordRequest"
      responses:
        200:
          description: password reset
        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

  /invite/token/generate:
    post:
      tags:
        - admin
      security:
        - key: []
      operationId: inviteTokenGenerate
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/inviteTokenGenerateRequest"
      responses:
        201:
          description: invitation tokens created
        400:
          description: invitation tokens not created
        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/environmentShares"
        401:
          description: unauthorized
        404:
          description: not found
        500:
          description: internal server error

  /detail/share/{shrToken}:
    get:
      tags:
        - metadata
      security:
        - key: []
      operationId: getShareDetail
      parameters:
        - name: shrToken
          in: path
          type: string
          required: true
      responses:
        200:
          description: ok
          schema:
            $ref: "#/definitions/share"
        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/environmentSharesList"
        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"
  #
  # share
  #
  /access:
    post:
      tags:
        - share
      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

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

  /unaccess:
    delete:
      tags:
        - share
      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:
        - share
      security:
        - key: []
      operationId: unshare
      parameters:
        - name: body
          in: body
          schema:
            $ref: "#/definitions/unshareRequest"
      responses:
        200:
          description: share 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
      shrToken:
        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"

  environmentSharesList:
    type: array
    items:
      $ref: "#/definitions/environmentShares"

  environmentShares:
    type: object
    properties:
      environment:
        $ref: "#/definitions/environment"
      shares:
        $ref: "#/definitions/shares"

  errorMessage:
    type: string

  forgotPasswordRequest:
    type: object
    properties:
      email:
        type: string

  inviteTokenGenerateRequest:
    type: object
    properties:
      tokens:
        type: array
        items:
          type: string

  inviteRequest:
    type: object
    properties:
      email:
        type: string
      token:
        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
      limitless:
        type: boolean
      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

  resetPasswordRequest:
    type: object
    properties:
      token:
        type: string
      password:
        type: string

  share:
    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/shareMetrics"
      createdAt:
        type: integer
      updatedAt:
        type: integer

  shares:
    type: array
    items:
      $ref: "#/definitions/share"

  shareMetrics:
    type: array
    items:
      type: integer

  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
      shrToken:
        type: string

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

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

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

  updateShareRequest:
    type: object
    properties:
      shrToken:
        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"