# 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: [email protected]
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