# Example YAML to get you started quickly.
# Be aware that YAML has indentation based scoping.
# Code completion support is available so start typing for available options.
swagger: '2.0'

# This is your document metadata
info:
  title: Helix Web Services
  description: Provides HTTP Access to Helix Service Applications
  contact:
    name: Perforce Support
    email: support@perforce.com
  license:
    name: MIT
  version: "2016.1.0"

schemes: ["http","https"]

consumes: ["application/json"]

produces: ["application/json"]

securityDefinitions:
  ticket_auth:
    type: apiKey
    in: header
    name: Authorization
    description: |
      To use HWS, obtain a ticket using the /login method.

security:
  - ticket_auth: []

# Describe your paths here
paths:
  #---------------------------------------------------------------------
  # Config
  #---------------------------------------------------------------------
  /api/hws/v16.1/servers:
    get:
      operationId: getP4dServers
      description: |
        The list of registered p4d servers in your cluster.

        This is provided by a special set of configuration files in the system.
        For more information, consult the Helix Web Services user guide.
      responses:
        200:
          description: Server messages.
          schema:
            type: array
            items:
              $ref: '#/definitions/P4dConfigId'
  #---------------------------------------------------------------------
  # Login
  #---------------------------------------------------------------------
  /api/hws/v16.1/login:
    post:
      operationId: login
      description: |
        Logs into Helix Web Services.

        This can either be a p4d instance or Helix Cloud, depending upon the
        configuration of your Helix Web Services instance.
      responses:
        200:
          description: Object with ticket to use for Basic auth password.
          schema:
            $ref: '#/definitions/LoginResponse'
      security: []
  #---------------------------------------------------------------------
  # Status
  #---------------------------------------------------------------------
  /api/hws/v16.1/status:
    get:
      operationId: getStatus
      description: |
        A simple structure to monitor for "problems" an admin should take care of, and, report the current application version.

        This method does not require authentication.
      responses:
        200:
          description: Server messages.
          schema:
            $ref: '#/definitions/HWSStatus'

# NOTE: All responses really should include additionalProperties, since you'll
# never be able to completely type most data coming from the server. Just "likely"
# data.
definitions:
  HWSStatus:
    type: object
    properties:
      status:
        type: string
        description:
          When "OK" the server should be considered to be operating normally
      version:
        type: string
        description: |
          The version of Helix Web Services server.
  LoginRequest:
    type: object
    description: |
      Captures the login information we need for logging into either a p4d server or our "authentication source".
    properties:
      user:
        type: string
        description: Usually the Perforce username
      password:
        type: string
      serverLogins:
        type: array
        items:
          $ref: '#/definitions/ServerLoginRequest'
  LoginResponse:
    type: object
    description: |
      Either of our login methods return a ticket, which is then used as a password in a basic authentication scheme.

      When this is returned from the explicit p4d login, this is a host unlocked ticket, acceptable for using with a local client.
    properties:
      ticket:
        type: string
  P4dConfigId:
    type: object
    description: |
      Identification of servers the Helix Web Services instance can connect to.
    properties:
      id:
        type: string
        description: A simple string identifier (alphanumeric characters only, please)
      name:
        type: string
        description: A display string, not guaranteed to be unique
      description:
        type: string
        description: A simple textual description, for potential selection by clients.
  ServerLoginRequest:
    type: object
    properties:
      id:
        type: string
        description: The server's ID
      user:
        type: string
      password:
        type: string