About This Manual

This guide covers administering and developing against the Helix Web Services. Helix Web Services provide common services and APIs that interact with the Helix Versioning Engine.

A Helix Web Services server is a web server, and it’s APIs are fundamentally based on the HTTP protocol. Not all aspects of the Helix Versioning Engine are provided by Helix Web Services, vice versa. Some services provided by Helix Web Services are not available in the Helix Versioning Engine.

Please give us feedback

If you have any feedback for us, or detect any errors in this guide, please email details to manual@perforce.com.

Overview

Knowledge Required

For deployment and configuration tasks, this guide assumes that you are experienced with administering web applications. You should be conceptually comfortable with Nginx and Unicorn. It is not necessary to have expert knowledge of these systems, but you should understand what their roles are without further clarification. If you require more knowledge, please consult online guides available from each of the primary sites:

Additionally, while this guide interfaces with the Helix Versioning Engine, we assume you are familiar with it. For more information about the Helix Versioning Engine, please become familiar with the following online guides:

For client development tasks, this guide assumes you are comfortable with the HTTP protocol. While it is not required to know Ruby, we provide a client SDK for Ruby, which may be easier to understand initially. If you do not use our Ruby client SDK, you will need to create an SDK for your platform, likely combined with a JSON parser.

Release compatibility of the API

Helix Web Services built and tested against a corresponding major release of the Helix Versioning Engine. For example, the '2015.1' release of Helix Web Services is validated using the '2015.1' of the Helix Versioning Engine. Using Helix Web Services against a non-corresponding Helix Versioning Engine instance will likely work, with some caveats.

Each major version of the Helix Versioning Engine can contain additional fields to the data returned by various methods. You will likely need to take care to ensure that your application does not assume a strict set of fields. Occasionally, there are subtle behavioral differences that may also require subtle shifts in logic. In the end, you will need to validate your code against the Helix Versioning Engine version you are using in production.

Architecture of the API

Helix Web Services is a Ruby web application, that is intended to sit behind a reverse proxy server, such as nginx. The reverse proxy server should handle the configuration of SSL for the web services, and can host other web applications from the Helix suite. Helix Web Services currently deploys into a single unicorn instance, on Linux machines.

Each Helix Web Services instance should not maintain state. You should be able to launch more than one Helix Web Services instance, and configure your reverse proxy to handle load balancing. You can also architect your system using services such as haproxy for load balancing. Using haproxy and nginx is beyond the scope of this documentation guide; we assume you are an experienced systems administrator when it comes to clustered web application deployment.

Deploying Helix Web Services

Helix Web Services can be deployed from a source tarball distribution or from installed packages. Starting up web services from a source tarball is similar to working with code checked out from our source distribution.

To be clear, Helix Web Services will be set up to run a single application server instance. This application server will run on an unprivileged port, like 9000. It’s expected that Helix Web Services would be a part of a greater ecosystem of web applications, likely proxied by a web server such as Nginx. Our package installation includes a post-install configuration script that configures other services on the local machine to make it easy.

Deploying from a source tarball

The following steps will launch a Helix Web Services instance in the current terminal session. This is not intended for a production installation, but may be valid for evaluating the product or experimenting with customizing Helix Web Services from source.

Prerequisites to working with our source tarball:

  1. Ruby 2.2

  2. An installed Perforce server

Other Ruby variations will likely work, we do not test them.

Installation steps:

  1. Run: tar xzf helix-web-services-[VERSION].tar.gz

  2. Run: cd helix-web-services-[VERSION]/helix_web_services

  3. Run: bundle install

  4. Run: bundle exec foreman start

Deploying from Packages

Note
 Right now you can only obtain unsigned pre-release packages from our workshop website. See the project page at: https://swarm.workshop.perforce.com/projects/perforce-software-helix-web-services/

Install the package using the appropriate platform tool:

  • On Debian or Ubuntu systems, run dpkg -i helix-web-services-[VERSION].deb

  • On Redhat or CentOS systems, run rpm -i helix-web-services-[VERSION].rpm

After installation, run the configuration script:

sudo /opt/perforce/helix-web-services/bin/hws_configure

See Deployment Configuration for more details on post-install configuration.

This will have prepared both helix_web_services and nginx startup scripts. You should make any adjustments to your system configuration if you need to, and then startup the services.

On Ubuntu, this would take the form:

sudo service helix_web_services start
sudo service nginx start

If this machine already has an existing nginx or perforce server configuration, you will have to manually configure /etc/nginx/nginx.conf or adjust the system configuration for Helix Web Services. See Configuration.

Using hws_console to verify your deployment

After installation, you may want to quickly check that your configuration is working as you think it should. You can use the hws_console application to quickly run a few commands in a Ruby console. A default method, client_for(user, password) is available to let you sign in and start running commands.

First, from your login shell, run:

/opt/perforce/helix-web-services/bin/hws_console

You should be dropped into a Pry session, that will look like the following:

From: /opt/perforce/helix-web-services/embedded/lib/ruby/gems/2.2.0/gems/helix_web_services-2015.1.0.pre1/bin/hws_console @ line 18 :

    13:       ssl: {verify: false}
    14:   )
    15: end
    16:
    17: # Drop into the console
 => 18: binding.pry

[1] pry(main)>

At the prompt, [1] pry(main)>, you can create a client and interact with it.

Say you’re using the default configuration, which creates an empty Perforce server with the user super with password superuser1A!. You can run the following commands:

c = client_for('super', 'superuser1A!')
c.depots

While there will be a lot of console debugging output, at the end, you’ll see the list of depots in your system.

At this point, c is an instance of the HelixWebServicesClient. See the Ruby API documentation for more details on what you can run.

Uninstalling Helix Web Services

Completely removing Helix Web Services from the system boils down to a few steps:

  • Remove the helixwebservices account and group

  • Remove the Upstart configuration at /etc/init/helix_web_services.conf

  • Remove temporary data and logging directories: /var/lib/perforce/helix_web_services, /var/log/perforce/helix_web_services

  • Uninstall or reconfigure nginx

  • Uninstall or reconfigure perforce-server

  • Run the system package uninstaller, e.g., apt-get remove helix-web-services, dpkg -r helix-web-services, etc.

Configuration

Deployment Configuration

There are a few main tasks to perform after just running the installer to get your system fully operational. The script /opt/perforce/helix-web-services/bin/hws_configure can be run on most "clean" operating systems to perform all of these steps. Not all of these steps will be performed, necessarily. For example, if you already have nginx running, we will not modify your system configuration. You will have to configure a reverse proxy to the unicorn server running at port 9000.

Description Default set by hws_configure

Notes

Establish the user account for running Helix Web Services

helixwebservices

Will not be created if already exists

Create directory for temporary data, assign to user account

/var/lib/perforce/helix_web_services

Will not be created if already exists

Create directory for logging data, assign to user account

/var/log/perforce/helix_web_services

Will not be created if already exists

Link upstart configuration

/etc/init/helix_web_services.conf is linked from /opt/perforce/helix-web-services/etc/init/helix_web_services.conf

Install and configure nginx

nginx is installed from system packages, a self-signed key is created or installed, and the default /etc/nginx/nginx.conf is setup as a reverse proxy to Unicorn running at port 9000

If nginx is already installed, none of these steps will be performed.

Install and configure a Helix Versioning Engine for evaluation

Installs the perforce-server system package, and then configures a helix-evaluation instance to run at port 1666.

For details of the steps taken, review the script code online at:

https://swarm.workshop.perforce.com/projects/perforce-software-helix-web-services/files/main/source/helix_web_services/bin/hws_configure

Available Application Settings

System default settings for Helix Web Services can be set by creating a YAML file at /etc/perforce/helix_web_services.conf. If you’re unfamiliar with YAML, you simply use the variables below in simple key-value pairs. Pay attention, however, to the type of the variable. In many cases we use strings when you might have thought it were a number.

For example:

/etc/perforce/helix_web_services.conf

P4PORT: 'perforce.mycompany.com:1999'

Many settings in Helix Web Services are overridable by HTTP headers on a per-request basis. The "Overridable" column in the table below means you can specify this header. If it is not available, you can only specify the configuration in the system config file. For more information on specifying the system header, see Per-Request Configuration.

Variable Type Overridable Description Default

COMMAND_WHITELIST

Array

No

Allows access to run commands via GET /p4/v[api]/commands/[command] or POST /p4/v[api]/commands/[command]. Each element in the array is either the name of a command to allow, or an array of the command name and any required arguments.

["info", ["files", "-m"]]

CUSTOM_SCRIPTS

String

No

The local directory that will load up user defined Ruby scripts.

/var/lib/perforce/helix_web_services/scripts

ENABLE_GIT_FUSION

Boolean

No

Switch to enable GitFusion endpoints.

false

ENABLE_HELIX_CLOUD_AUTH

Boolean

No

Use Helix Cloud as the authentication source.

false

ENABLE_HELIX_CLOUD_PROJECTS

Boolean

No

Enable Helix Cloud as a project source.

false

HVE_PROJECTS_PATH

String

Yes

The depot location in the Helix Versioning Engine that hosts all projects in that server.

P4HOST

String

Yes

The hostname for the perforce server, e.g., perforce.example.com

P4PORT

String

Yes

The port number (or port and hostname combination) that indicates our Perforce connection

1666

P4CHARSET

String

Yes

The charset value for P4 connections. Set to none if you are connecting to a non-unicode server.

auto

P4PASSWD

String

Yes

The user password to use for p4 connections. For many cases, like where the authentication source is a p4d server, this will default to the authentication token password.

SERVICE_CONFIGURATION

String

No

Local file location that defines how services are to be configured.

/etc/perforce/services.json

TRUST_FINGERPRINTS

String

No

Local file path that indicates a list of allowed SSL fingerprints.

WORKSPACE_DIR

String

No

The local directory used for generating temporary Perforce Client Workspaces to do some basic operations.

/var/lib/perforce/helix_web_services/workspaces

Client Application Development

In general, your client application is going to need to:

  • Know the Helix Versioning Engine topology

  • Obtain login tokens for Helix Versioning Engine (using [post_auth_v1_login])

  • Call other methods on the system.

Your application may use a single Helix Web Services instance to interact with multiple Helix Versioning Engines. In these cases, you will need to specify which versioning engine you are interacting with. In cases you are only using one Helix Versioning Engine, your application can then specify system wide settings. See Configuration for more details.

Working with Helix Web Services for a client generally involves making a single request at a time. Many of our core methods mimic the set of commands available to the p4 application. But if you need to make a combined set of `p4 commands, ideally, there are extended "services" available, that handle that interaction. So, in general, your client application only needs to make one web service call at a time.

Authentication

Almost every Helix Web Services method requires authentication. We support HTTP Basic Authentication, using the login and p4 ticket as credentials. Obtain a ticket via [post_auth_v1_login].

Say the user jdoe has obtained the ticket B984EF267963F434BB51C063EE86E8F9. The corresponding HTTP header to add to each request would be:

Authorization: Basic amRvZTpCOTg0RUYyNjc5NjNGNDM0QkI1MUMwNjNFRTg2RThGOQ==
Note
 You can easily generate the basic header on most Unix systems using the echo and base64 commands. For example, to generate the header above, would be the command echo -n jdoe:B984EF267963F434BB51C063EE86E8F9 | base64

Per-Request Configuration

Each request can specify HTTP headers to indicate override known settings the system.

Each custom header takes the format:

X-Perforce-Helix-Web-Services-[KEY]

See Configuration for the list of available keys.

For example, to change the P4PORT to be used, which identifies a separate Helix Versioning Engine, you’d set this header:

X-Perforce-Helix-Web-Services-P4PORT: helix-eu.mycompany.com:1666

Error Conventions

Upon success, methods of Helix Web Services return the 200 HTTP status code. If your authentication token is not valid, you will receive 403 error, which means you need to update your login token (using [post_auth_v1_login]).

401 errors will likely originate from the Helix Versioning Engine. In this case, we provide information to the client application via a JSON object. This object will contain three main properties:

Property Description

MessageCode

A numeric ID for the problem, typically defined by the Helix Versioning Engine. Should be the same value as Error::GetGeneric().

MessageSeverity

Mirrors the severity levels of Error::GetSeverity(). Generally going to be 3 or 4.

MessageText

Informational text that will likely not be localized appropriately for the user.

When 500 errors happen, a serious problem has occurred, which may mean an important subsystem is compromised. Do not expect a response body. The problem will have to be investigated on the server side. Your client should not attempt further communication with Helix Web Services.

Ruby Client SDK

If your application is written in Ruby, you can use our provided Ruby client SDK. This SDK is currently available as part of the Helix Web Services source code, in the helix_web_services_client directory. Many Helix Web Services methods refer to this client SDK as the Ruby API.

Basic Ruby Client SDK usage

There are really two primary methods:

  1. execute_method_with_body

  2. execute_method_no_body

Along with signing in via the constructore

These methods will generally parse the JSON response, and throw exceptions in case of any errors reported by the underlying server.

require 'helix_web_services_client'

client = HelixWebServicesClient.new({
    :url => 'https://helix.example.com/hws',
    :user => 'jdoe',
    :password => 'joesupersecret'
})

# Get starting list of depots
depots = client.execute_method_no_body(:get, '/p4/v[api]/files')

# Print depot names
depots.each { |d| puts d['name'] }

# Make a user
client.execute_method_with_body(:post, '/p4/v[api]/users', nil, {
    'User': 'new_user',
    'FullName': 'Steve Austin',
    'Email': 'saustin@example.com'
})

You can additionally fetch the p4 ticket via the client.ticket property. If you store that, you can create a new HelixWebServicesClient specifying that via ticket instead of password.

Models in the Ruby Client SDK

Most HTTP methods that correspond to commands of the p4 application, do not alter data from the Helix Versioning Engine. This can be inconvenient for application development. For example, dates are inconsistently represented, sometimes as strings, other times as timestamps. Keys that represent the same concept show up in different cases in the output data.

We’ve developed the OpenModel class to help this out. Because a single version of Helix Web Services can interact with multiple instances Helix Versioning Engines at different versions, we do not want to restrict the data coming out of the server. The OpenModel class looks for case alternatives that might appear. It also provides a Ruby-like coding standard.

# Get starting list of depots
depots = client.depots

# The depot name
#
# If you call the singular method using our basic API this key is sometimes
# referred to by `name`, sometimes as `Depot`
depots.first.depot_or_name

# In some listings, this is an integer represented as a string.
#
# Instead of a number, returns a Ruby Time object.
#
# Note that you should grab the offset value from the 'serverDate' field from
# the `p4 info` command.
depots.first.date_as_time(offset)

# Can still make a user fairly easily just using Hashes
client.create_user({
    'User' => 'new_user',
    'FullName' => 'Steve Austin',
    'Email' => 'saustin@example.com'
})

# Updating specs should use upper case syntax.
depot = client.depot('to_edit')
depot.Description = "Updating the description"
client.update_depot(depot)

Obtaining the Client SDK

In order to use the client SDK, you’d first need to obtain a copy of the Helix Web Services source from the Perforce workshop. Visit the workshop at https://swarm.workshop.perforce.com/. On that site, you can sign up a new account. Documentation on this process is provided via that website.

Once you have an account, you can then retrieve code via the Helix Versioning Engine available at workshop.perforce.com:1666. The source code is available at //guest/perforce_software/helix-web-services/main/…​ Use any Perforce client application, such as p4 or P4V to connect and retrieve the source code.

Official releases of Helix Web Services may publish this client SDK to rubygems. Stay tuned!

HTTP Protocol Reference

Each section includes methods related to a particular topic or resource.

Configuration Methods

Git Fusion Methods

Repositories

Keys

Helix Sync Methods

Changes

Clients

Helix Versioning Engine Methods

Branches

Changes

Clients

Commands

Counters

Depots

Files

Groups

Jobs

Labels

Login

Protections

Servers

Streams

Triggers

Users

Project Services

Configuration of Available Services

GET /config/v1/services

Return the list of available Helix services. Each service represents an application-level subsystem in your Helix installation.

Returns the service configuration JSON as defined in Appendix D: Service Configuration JSON. See the appendix for details on the JSON format.

Request Headers
Header Name Notes

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

Returns the service configuration JSON as defined in Appendix D: Service Configuration JSON. See the appendix for details on the JSON format.

[
  {
    "type": "p4d",
    "uri": "p4://perforce.mycompany.com.1666"
  },
  {
    "type": "git-fusion",
    "uri": "ssh://git-fusion.mycompany.com"
  }
]

Helix Git Fusion Repositories

GET /git-fusion/v1/repos

Lists all configured repositories readable by the current user.

Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

Response will consist of names of configured repositories as well as their id’s - which are Git Fusion encoded versions of the name strings.

[
  {
    "id": "namespace_0xS_project",
    "name": "namespace/project",
  },
  {
    "id: "repository_name",
    "name": "repository_name",
  }
]

GET /git-fusion/v1/repos/[repo]

Return configuration for specified repository. Grabs and returns contents of p4gf_config file for given repository.

Request URL Path Parameters
Parameter Description

repo

See Repository name encoding
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

Response returns a JSON representation of contents of the p4gf_config file for chosen repo.

{
  "description": "Sample repo",
  "branches": {
    "master": {
      "depot_path" : "//depot/sample_repo_name/...",
      "client_path": "..."
    }
  }
}

PUT /git-fusion/v1/repos/[repo]

Submits a p4gf_config file to create or update a repository configuration. If repository does not exist or has been previously deleted - saves contents of the config file to a new p4gf_config file. If the repository already has been initialised - replaces the all of the file contents for p4gf_config for specified repository.

Request URL Path Parameters
Parameter Description

repo

See Repository name encoding
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request JSON Body

The request should be file contents of a p4gf_config file.

An example request body might look like:

[@repo]
description = Testing repo description

[prep]
git-branch-name = prep
view = //depot/testing_repo_name/... ...
Response Headers
Header Name Notes

Content-Type

application/json
Response Body

Response returns an object with 'config' value that contains the contents of p4gf_config or an error message.

If upload exists successfully - an example response might look like this:

{
  "description": "Testing repo description",
  "branches": {
    "prep": {
      "depot_path" : "//depot/testing_repo_name/...",
      "client_path": "..."
    }
  }
}

PATCH /git-fusion/v1/repos/[repo]

Updates values in the repository configuration. This will find specified parameters and update its values for a specified repository configuration file.

Request URL Path Parameters
Parameter Description

repo

See Repository name encoding
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request JSON Body

This is a sample string with values to be replaced.

{
  'description' = 'Updated description',
  'branches': {
    'master': {
      'git-branch-name' = 'other-branch'
    }
   }
}
Response Headers
Header Name Notes

Content-Type

application/json
Response JSON Body

See Error Conventions for the format of failures.

DELETE /git-fusion/v1/repos/[repo]

Deletes the repository configuration (p4gf_config file). Contents of the repository are not deleted from Perforce.

Request URL Path Parameters
Parameter Description

repo

See Repository name encoding
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response JSON Body

See Error Conventions for the format of failures.

Repository name encoding

All URL’s containing a repository path should have that path encoded to Git Fusion standards to enable appropriate routing. Encoding has to be done by client, according to the table below:

Character Encoding Unencoded repository name Encoded repository name Sample URL with encoded repository name

/ (forward slash)

_0xS_

foo/bar

foo_0xS_bar

/git-fusion/v1/repos/foo_0xS_bar

: (colon)

_0xC_

foo:bar

foo_0xC_bar

/git-fusion/v1/repos/foo_0xC_bar

Helix Git Fusion User Keys

GET /git-fusion/v1/users/[user]/keys

Returns a list of all keys for a user.

Request URL Path Parameters
Parameter Description

user

See Encoding Perforce username & SSH key names
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

Response consists of a list of hashes - each entry containing a key for specified user with file name under which the key is stored.

[
    {
        'key_name': 'key_file_name',
        'user': 'jdoe',
        'key': "-----BEGIN PUBLIC KEY-----\nSSHKEYCONTENT\n-----END PUBLIC KEY-----"
    },
    {
        'key_name': 'other_key_file_name',
        'user': 'jdoe',
        'key': "-----BEGIN PUBLIC KEY-----\nSSHKEYCONTENT2\n-----END PUBLIC KEY-----"
    }
]

PUT /git-fusion/v1/users/[user]/keys/[key_name]

Submits a new SSH key for specified user under chosen name.

Request URL Path Parameters
Parameter Description

user

Encoded version of perforce username. See Encoding Perforce username & SSH key names

key_name

Encoded version of key name. See Encoding Perforce username & SSH key names
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request JSON Body

The request should be file contents of a new SSH key that should be submitted.

An example request body might look like:

-----BEGIN PUBLIC KEY-----
SSHKEYCONTENT5
-----END PUBLIC KEY-----
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

See Error Conventions for the format of failures.

DELETE /git-fusion/v1/users/[user]/keys/[key_name]

Deletes specified key for chosen user.

Request URL Path Parameters
Parameter Description

user

Encoded version of perforce username. See Encoding Perforce username & SSH key names

key_name

Encoded version of key name. See Encoding Perforce username & SSH key names
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response JSON Body

See Error Conventions for the format of failures.

DELETE /git-fusion/v1/users/[user]/keys

Deletes all SSH keys for specified user.

Request URL Path Parameters
Parameter Description

user

See Encoding Perforce username & SSH key names
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response JSON Body

See Error Conventions for the format of failures.

Encoding Perforce username & SSH key names

All perforce usernames and SSH key names present in URL’s must be encoded by replacing reserved characters as defined by RFC3986 section 2.2 general-delimeters with a percent sign followed by a hexadecimal representation of codepoint of the character.

SubmitShelf(project, change ID)

Helix Sync Changes

Many operations for Helix Sync are related to manipulating changelists in order to share state across devices.

GET /helix-sync/v1/[project]/last-change

Return the latest change number available for a project.

This method can have multiple implementations.

To use a "Helix Versioning Engine Project" as defined in Appendix B: Helix Versioning Engine Project JSON, you will need to ensure the HVE_PROJECT_PATH is set. This can be set on a request, or on the system as a whole.

Request URL Path Parameters
Parameter Description

project

The project ID, see Appendix A: Project JSON
Request URL Query Parameters
Parameter Required? Description

default

No

If set, we will return this value instead of issuing a 404 reply in place of the nonexisting changelist number.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

See Error Conventions for the format of failures.

The response of this method is a single JSON object with a single property, called change, which indicates the latest changelist number.

GET /helix-sync/v1/[project]/pending

Returns the pending changelist to be used as the primary shelf for this project for the authenticated user. If such a changelist does not exist, you can use [post_helix_sync_v1_changes_project] to create one.

By default, will return a 404 (not found) if such a changelist does not exist. If you have set a default value via the URL request query parameter, that value will be returned instead, and you should receive an HTTP 200 status.

This method can have multiple implementations.

To use a "Helix Versioning Engine Project" as defined in Appendix B: Helix Versioning Engine Project JSON, you will need to ensure the HVE_PROJECT_PATH is set. This can be set on a request, or on the system as a whole.

Request URL Path Parameters
Parameter Description

project

The project ID, see Appendix A: Project JSON
Request URL Query Parameters
Parameter Required? Description

default

No

If set, we will return this value instead of issuing a 404 reply in place of the nonexisting changelist number.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

See Error Conventions for the format of failures.

The response of this method is a single JSON object with a single property, called change, which indicates the latest changelist number.

In the case no change exists, there will be no response body, and a 404 response code will be returned instead.

DELETE /helix-sync/v1/:project_id/pending

Deletes the pending changelist for project.

Request URL Path Parameters
Parameter Description

project

The project ID, see Appendix A: Project JSON
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

See Error Conventions for the format of failures.

GET /helix-sync/v1/[project]/preview

Generates the "resolve plan" for what the Helix Sync method would implement for the method [post_helix_sync_v1_changes_project_pending].

The resolve plan is an array of resolution tasks to handle.

Request URL Path Parameters
Parameter Description

project

The project ID, see Appendix A: Project JSON
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

See Error Conventions for the format of failures.

Warning
 The details of the resolve plan JSON are not yet finalized.

POST /helix-sync/v1/[project]/submit

Requests to submit the particular pending changelist for the project. It’s assumed that what you want to submit has been shelved, and no open files remain on your local clients.

There is no response body when this method succeeds, only in failure.

This method can have multiple implementations.

To use a "Helix Versioning Engine Project" as defined in Appendix B: Helix Versioning Engine Project JSON, you will need to ensure the HVE_PROJECT_PATH is set. This can be set on a request, or on the system as a whole. This implementation only runs a submit -e on the pending changelist. No resolution is currently performed.

Request URL Path Parameters
Parameter Description

project

The project ID, see Appendix A: Project JSON
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

See Error Conventions for the format of failures.

Helix Sync Clients

POST /helix-sync/v1/[project]/clients/device

Creates a new client workspace for use by helix sync for a particular device.

This method can have multiple implementations.

To use a "Helix Versioning Engine Project" as defined in Appendix B: Helix Versioning Engine Project JSON, you will need to ensure the HVE_PROJECT_PATH is set. This can be set on a request, or on the system as a whole.

Request URL Path Parameters
Parameter Description

project

The project ID, see Appendix A: Project JSON
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

Requires a JSON object with the following parameters:

Property Description

project

The project ID, see Appendix A: Project JSON

device

A unique ID for the device in use.

root

The directory path on the user’s machine to use.
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

Returns a JSON object with a client property, indicating the client name to use.

DELETE /helix-sync/v1/[project]/clients/device/[device]

Removes the client workspace associated for the project associated with a particular device.

Request URL Path Parameters
Parameter Description

project

The project ID, see Appendix A: Project JSON

device

The device ID associated with the client, see Appendix A: Project JSON
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

See Error Conventions for the format of failures.

POST /helix-sync/v1/[project]/clients/shelf

Creates a new client workspace for use by helix sync for the main shelf.

This method can have multiple implementations.

To use a "Helix Versioning Engine Project" as defined in Appendix B: Helix Versioning Engine Project JSON, you will need to ensure the HVE_PROJECT_PATH is set. This can be set on a request, or on the system as a whole.

Request URL Path Parameters
Parameter Description

project

The project ID, see Appendix A: Project JSON
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

Requires a JSON object with the following parameters:

Property Description

project

The project ID, see Appendix A: Project JSON

root

The directory path on the user’s machine to use.
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

Returns a JSON object with a client property, indicating the client name to use.

DELETE /helix-sync/v1/[project]/clients/shelf

Removes the client workspace associated for the project for the purposes of shelving.

Request URL Path Parameters
Parameter Description

project

The project ID, see Appendix A: Project JSON
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

See Error Conventions for the format of failures.

Helix Versioning Engine Branches

GET /p4/v[api]/branches

Lists available branches in the system. The resources of this list are summaries of branches in the system.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

The values of this method are based on the result of the p4 -ztag branches command. For more field information refer to the command reference.

See Error Conventions for the format of failures.

An example response body might look like:

[
  {
    "branch": "manually",
    "Update": "1437153920",
    "Access": "1437153920",
    "Owner": "jdoe",
    "Options": "unlocked",
    "Description": "Created by jdoe.\n"
  },
  {
    "branch": "new_branch_CEUXQMYN",
    "Update": "1437164204",
    "Access": "1437164204",
    "Owner": "",
    "Options": "unlocked",
    "Description": "Something for the kids\n"
  }
]
Ruby Client

See HelixWebServicesClient#branches

POST /p4/v[api]/branches

Creates a new branch specification, like the p4 branch command.

There are no other parameters to this method.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

Properties of the JSON object are the form fields of the p4 branch command.

{
  "Branch": "my-project-main",
  "Description": "Branch my project from main to dev.\n",
  "View": ["//depot/main/my-project/... //depot/dev/my-project/..."]
}
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#create_branch

GET /p4/v[api]/branches/[branch]

Return branch details, similar to the p4 branch -o command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

branch

The branch name.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Data

Returns the form fields of the p4 -ztag branch [branch name] command. For more information, see the command reference. The main difference between the details and list view is the inclusion of the View field.

Example JSON Response
{
  "Branch": "my-project-main",
  "Update": "2015/07/22 11:34:14",
  "Access": "2015/07/22 11:34:14",
  "Description": "Branch my project from main to dev.\n",
  "Options": "unlocked",
  "View": [
    "//depot/main/my-project/... //depot/dev/my-project/..."
  ]
}
Ruby Client

See HelixWebServicesClient#branch

PATCH /p4/v[api]/branches/[branch]

Update branch specifications, similar to the p4 branch command. Only the specified parameters in the body will be changed.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

branch

The name of the branch
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

A single JSON object containing form fields of the p4 -ztag branch [branch name] command.

Response Headers
Header Name Notes

Content-Type

application/json
Example JSON Request Body
{
  "Description": "The updated my-project-main description.\n",
  "Owner": "saustin"
}
Ruby Client

See HelixWebServicesClient#update_branch

client.update_branch({
  "Branch" => 'my_branch_id',
  "Description" => "The updated my-project-main description.\n",
  "Owner" => "saustin"
})
DELETE /p4/v[api]/branches/[branch]

Removes the branch specification, similar to the p4 branch -d command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

branch

The name of the branch
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#delete_branch

Helix Versioning Engine Changes

GET /p4/v[api]/changes

List changelist summaries, with some common filtering options.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request URI Query Parameters

The following parameters are all optional.

Key Description

max

Limits the number of results returned See the changes -m option.

status

Only return results with the indicated status. See the changes -s option.

user

Only return changes owned by this particular user. See the changes -u option.

files

Limit changes to the depot path expressions. See the changes command description.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

The values of this method are based on the result of the p4 -ztag changes command.

See Error Conventions for the format of failures.

An example response body might look like:

[
  {
    "change": "20",
    "time": "1437589210",
    "user": "jdoe",
    "client": "AUERUGBO",
    "status": "submitted",
    "changeType": "public",
    "path": "//depot/dev/Experimental/*",
    "desc": "Upload two experimental files\n"
  },
  {
    "change": "19",
    "time": "1437589209",
    "user": "jdoe",
    "client": "PRQSCBCT",
    "status": "submitted",
    "changeType": "public",
    "path": "//depot/test-UDQXTCFI/Experimental/*",
    "desc": "Edited files\n"
  }
]
Ruby Client

See HelixWebServicesClient#changes

POST /p4/v[api]/changes

Create a new changelist that can affect multiple files using different kinds of actions. If you require the ability to integrate or move, for example, you can use this method.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request JSON Body

The request should be a JSON object with the following properties:

Parameter Description Type Parameter Type Required

Description

Textual description of the change

string

body

No

Files

Array of file change actions to take (See below)

array

body

No

Each object in the Files array consists of the following properties:

Parameter Description Required

DepotFile

The depot path specifier for the action

Yes

FromDepotFile

When the Action is a branch or move, this indicates the source of the operation.

No

Action

One of upload, branch, or move.

Yes

Content

If the Action is upload, this is the base-64 encoded file content.

No

RequireVersion

If the current version is not set at this version string, consider it an error.

No

An example JSON request body would look like:

{
  "Description": "My Test Change",
  "Files": [
    {
      "Action": "upload",
      "DepotFile": "//depot/example.txt",
      "Content": "SSBhbSBhIGxpdHRsZSB0ZWFwb3Q="
    }
  ]
}
Response Headers
Header Name Notes

Content-Type

application/json
Response JSON

See Error Conventions for the format of failures.

Ruby Client

See HelixWebServicesClient#create_change

GET /p4/v[api]/changes/[change]

Read details of a single changelist in the system.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

change

The changelist number.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response JSON Body

The values of this method are based on the result of the p4 -ztag describe command.

See Error Conventions for the format of failures.

An example response might look like this:

[
  {
    "change": "1",
    "user": "super",
    "client": "JGOJOUDY",
    "time": "1437581534",
    "desc": "A few basic adds\n",
    "status": "submitted",
    "changeType": "public",
    "path": "//depot/...",
    "depotFile": [
      "//depot/dev/Experimental/README",
      "//depot/main/My Project/README"
    ],
    "action": [
      "add",
      "add"
    ],
    "type": [
      "text",
      "text"
    ],
    "rev": [
      "1",
      "1"
    ],
    "fileSize": [
      "40",
      "34"
    ],
    "digest": [
      "5606AFCE00250FC14B2D932BAF5CE45B",
      "0FA2BDFCEACC2A445EFDF86BEB6D3F9F"
    ]
  }
]
Ruby Client

See HelixWebServicesClient#change

POST /p4/v[api]/changes/[change]

Submit shelved changes to the depot. Uses the p4 submit -e command to perform the submit.

This method will fail:

  1. If the changelist in question is not a pending changelist with a shelf.

  2. If any resolves are required.

  3. If any files are open on the pending changelist. You must revert all local changes before calling this method.

If the changelist is based on a stream client, this will generate a temporary stream client as appropriate.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

change

The changelist number.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response JSON Body

See Error Conventions for the format of failures.

Helix Versioning Engine Clients

GET /p4/v[api]/clients

Lists available clients in the system. The resources of this list are summaries of clients in the system.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

The values of this method are based on the result of the p4 -ztag clients command. For more field information refer to the command reference.

See Error Conventions for the format of failures.

An example response body might look like:

[
  {
    "client": "test_EEDOGMCS",
    "Update": "1437169680",
    "Access": "1437169680",
    "Owner": "",
    "Options": "noallwrite noclobber nocompress unlocked nomodtime normdir",
    "SubmitOptions": "submitunchanged",
    "LineEnd": "local",
    "Root": "/tmp/clients/test_EEDOGMCS",
    "Host": "",
    "Description": "Test EEDOGMCS\n"
  },
  {
    "client": "test_QBZEOHBJ",
    "Update": "1437169655",
    "Access": "1437169655",
    "Owner": "jdoe",
    "Options": "noallwrite noclobber nocompress unlocked nomodtime normdir",
    "SubmitOptions": "submitunchanged",
    "LineEnd": "local",
    "Root": "/Users/tristan/dev/hws",
    "Host": "localhost",
    "Description": "Test QBZEOHBJ\n"
  }
]
Ruby Client

See HelixWebServicesClient#clients

POST /p4/v[api]/clients

Creates a new client specification, like the p4 client command.

There are no other parameters to this method.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

Properties of the JSON object are the form fields of the p4 client command.

Response Headers
Header Name Notes

Content-Type

application/json
Example Request JSON
{
  "Client": "my_project_main",
  "Host": "superawesome",
  "Root": "/home/jimbob/my_project_main",
  "Description": "My project client on superawesome.\n",
  "Options": "noallwrite noclobber nocompress unlocked nomodtime normdir",
  "View": ["//depot/main/my-project/... //my_project_main/depot/main/my-project/..."]
}

Ruby Client Example

client.create_client({
  "Client" => "my_project_main",
  "Host" => "superawesome",
  "Root" => "/home/jimbob/my_project_main",
  "Description" => "My project client on superawesome.\n",
  "Options" => "noallwrite noclobber nocompress unlocked nomodtime normdir"
  "View" => ["//depot/main/my-project/... //my_project_main/depot/main/my-project/..."]
})
Ruby Client

See HelixWebServicesClient#create_client

GET /p4/v[api]/clients/[client]

Return client details, similar to the p4 client -o command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

client

The client name.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Data

Returns the form fields of the p4 -ztag client [client name] command. For more information, see the command reference. The main difference between the details and list view is the inclusion of the View field.

Example JSON Response
{
  "Client": "my_project_main",
  "Update": "2015/07/22 11:36:46",
  "Access": "2015/07/22 11:36:46",
  "Host": "superawesome",
  "Description": "My project client on superawesome.\n",
  "Root": "/home/user/my_project_main",
  "Options": "noallwrite noclobber nocompress unlocked nomodtime normdir",
  "SubmitOptions": "submitunchanged",
  "LineEnd": "local",
  "View": [
    "//depot/main/my-project/... //my_project_main/depot/main/my-project/..."
  ]
}
Ruby Client

See HelixWebServicesClient#client

PATCH /p4/v[api]/clients/[client]

Update client specifications, similar to the p4 client command. Only the specified parameters in the body will be changed.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

client

The client name.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

A single JSON object containing form fields of the p4 -ztag client [client name] command.

Response Headers
Header Name Notes

Content-Type

application/json
Example JSON Request Body
{
    "Options": "allwrite noclobber nocompress unlocked nomodtime rmdir"
}
Ruby Client

See HelixWebServicesClient#update_client

client.update_client({
    "Options" => "noallwrite noclobber nocompress unlocked nomodtime normdir"
})
DELETE /p4/v[api]/clients/[client]

Removes the client specification, similar to the p4 client -d command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

client

The client name.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#delete_client

Helix Versioning Engine Commands

GET /p4/v[api]/commands/[command]

Execute a Perforce command that takes no input.

This only allows commands that have been whitelisted on your system. See the Configuration section for details.

Request URL Path Parameters
Parameter Required Description

api

Yes

The Helix Versioning Engine API level.

command

Yes

The command name, that should be whitelisted in the system configuration. See Configuration.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

Responses are typically an array, mapped from the p4 -ztag output of a command.

See Error Conventions for the format of failures.

Ruby Client

See HelixWebServicesClient#command

POST /p4/v[api]/commands/[command]

Execute a Perforce command that accepts input, like a spec.

This only allows commands that have been whitelisted on your system. See the Configuration section for details.

Request URL Path Parameters
Parameter Required Description

api

Yes

The Helix Versioning Engine API level.

command

Yes

The command name, that should be whitelisted in the system configuration. See Configuration.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

The request body is a JSON structure, which becomes converted to a Ruby hash. This hash is used as input via the p4.input class property of P4Ruby. See P4.input for more information.

Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

See Error Conventions for the format of failures.

Ruby Client

See HelixWebServicesClient#command_with_input

Helix Versioning Engine Counters

GET /p4/v[api]/counters

Lists available counters in the system. The resources of this list are summaries of counters in the system.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

The values of this method are based on the result of the p4 -ztag counters command. For more field information refer to the command reference.

See Error Conventions for the format of failures.

An example response body might look like:

[
  {
    "counter": "build",
    "value": "54809"
  },
  {
    "counter": "build_good",
    "value": "54670"
  }
]
Ruby Client

See HelixWebServicesClient#counters

GET /p4/v[api]/counters/[counter]

Return counter details, similar to the p4 counter command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

counter

The counter name.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Data

Returns the form fields of the p4 -ztag counter [counter name] command. For more information, see the command reference. The main difference between the details and list view is the inclusion of the View field.

Example JSON Response
{
  "counter": "build",
  "value": "54809"
}
Ruby Client

See HelixWebServicesClient#counter

PUT /p4/v[api]/counters/[counter]

Sets a counter, like the p4 counter [counter] [value] command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

counter

The counter name.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

The request body is a JSON object with a value property.

For example:

{
  "value": "123"
}
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#set_counter

POST /p4/v[api]/counters/[counter]/increment

Increments a numerical counter, similar to the p4 counter -i command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

counter

The name of the counter
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#increment_counter

DELETE /p4/v[api]/counters/[counter]

Removes the counter specification, similar to the p4 counter -d command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

counter

The name of the counter
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#delete_counter

Helix Versioning Engine Depots

GET /p4/v[api]/depots

Lists available depots in the system. The resources of this list are summaries of depots in the system.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

The values of this method are based on the result of the p4 -ztag depots command. For more field information refer to the command reference.

See Error Conventions for the format of failures.

An example response body might look like:

[
  {
    "name": "depot",
    "time": "1437690306",
    "type": "local",
    "map": "depot/...",
    "desc": "Default depot"
  },
  {
    "name": "stream-test",
    "time": "1437690307",
    "type": "stream",
    "map": "depot/...",
    "desc": "A test depot\n"
  }
]
Ruby Client

See HelixWebServicesClient#depots

POST /p4/v[api]/depots

Creates a new depot specification, like the p4 depot command.

There are no other parameters to this method.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

Properties of the JSON object are the form fields of the p4 depot command.

For example:

{
  "Depot": "new_depot",
  "Description": "A new depot for stuff",
  "Type": "local",
  "Map": "new_depot/..."
}
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#create_depot

GET /p4/v[api]/depots/[depot]

Return depot details, similar to the p4 depot -o command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

depot

The depot name.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Data

Returns the form fields of the p4 -ztag depot [depot name] command. For more information, see the command reference. The main difference between the details and list view is the inclusion of the View field.

Example JSON Response
{
  "Depot": "depot",
  "Date": "2015/07/23 15:25:06",
  "Description": "Default depot\n",
  "Type": "local",
  "Map": "depot/..."
}
Ruby Client

See HelixWebServicesClient#depot

PATCH /p4/v[api]/depots/[depot]

Update depot specifications, similar to the p4 depot command. Only the specified parameters in the body will be changed.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

depot

The name of the depot
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

A single JSON object containing form fields of the p4 -ztag depot [depot name] command.

Response Headers
Header Name Notes

Content-Type

application/json
Example JSON Request Body
{
  "Description": "The updated new-depot description.\n"
}
Ruby Client

See HelixWebServicesClient#update_depot

DELETE /p4/v[api]/depots/[depot]

Removes the depot specification, similar to the p4 depot -d command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

depot

The name of the depot
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#delete_depot

Helix Versioning Engine Files

GET /p4/v[api]/files/[path]

Lists file information in the system. Responses are a combination of the output of three different common p4 commands: p4 -ztag depots, p4 -ztag dirs, and p4 -ztag files. We only list file information about the latest version of files. Files whose latest version is deleted, are not listed in the output.

Warning
 While you can retrieve the contents of files by specifying files instead of directories with the path parameter, understand this will very likely fail with large files. By default, the system is set up with a 60 second timeout, and large files will likely take longer than that to transfer. For file operations, especially for large files, you should consider using the P4API, and managing a local Helix Versioning Engine client workspace directly to the Helix Versioning Engine. Helix Web Services is intended for metadata-oriented operations.
Request URL Path Parameters
Parameter Required Description

api

Yes

The Helix Versioning Engine API level.

path

No

A path-like string to a depot or directory that contains other directories or files. Do not include wildcards.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

Responses are a combination of the output of three different common p4 commands: p4 -ztag depots, p4 -ztag dirs, and p4 -ztag files.

See Error Conventions for the format of failures.

An example response body might look like:

[
  {
    "depotFile": "//depot/dev/Experimental/new_file_RQTWSTFB",
    "rev": "1",
    "change": "190",
    "action": "add",
    "type": "text",
    "time": "1438031186"
  },
  {
    "dir": "//depot/dev/Experimental/subdir"
  }
]

If you don’t include a path, you’ll end up with a list of depots, which looks like this:

[
  {
    "name": "depot",
    "time": "1437690306",
    "type": "local",
    "map": "depot/...",
    "desc": "Default depot"
  },
  {
    "name": "stream-test",
    "time": "1437690307",
    "type": "stream",
    "map": "depot/...",
    "desc": "A test depot\n"
  }
]
Ruby Client

See HelixWebServicesClient#files

Recall that this method will return an OpenModel, that can assist in matching the different fields:

results = client.files
results.concat(client.files('//depot/dir')

names = results.map(&:name_or_dir_or_depot_file)
               .map{ |x| x.split('/').last }

PATCH /p4/v[api]/files/[path]

Provides a means for uploading content to a particular file or directory. This is a simplification of the POST /p4/v[api]/changes method, where action is always upload on all files.

Request URL Path Parameters
Parameter Required Description

api

Yes

The Helix Versioning Engine API level.

path

No

A path-like string to a depot or directory that contains other directories or files. Do not include wildcards.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request JSON Body

The Request JSON is an object with the following top-level parameters:

Property Required Description

Description

No

A text field describing the new file changes

Files

No

For multiple files, this is an array of objects, each containing the same DepotFile and Content data you would use as if this were a single file upload.

DepotFile

No

If this is a single file upload, this is the file path, relative to the path parameter in the URL.

Content

No

If this is a single file upload, this is the base64-encoded content

For example, here is a request uploading a single file with no URL path parameter in the request:

{
  "DepotFile": "depot/dir/complete/path",
  "Content": "SSdtIGEgbGl0dGxlIHRlYXBvdAo="
}

And here’a request uploading two files, expecting the path parameter in the request URL to be set to depot/dir/complete:

{
  "Files": [
    {
      "DepotFile": "README",
      "Content": "SSdtIGEgbGl0dGxlIHRlYXBvdAo="
    },
    {
      "DepotFile": "test.txt",
      "Content": "SSdtIGEgbGl0dGxlIHRlYXBvdAo="
    }
  ]
}

Both of the above requests would upload files to the same directory location.

Response Headers
Header Name Notes

Content-Type

application/json
Response JSON Body

See Error Conventions for the format of failures.

Ruby Client

See HelixWebServicesClient#upload_files, or HelixWebServicesClient#upload_file.

DELETE /p4/v[api]/files/[path]

Deletes a file if it exists in the system. This will mark the 'head' revision of the file as deleted. For more information, see the p4 delete command reference.

Request URL Path Parameters
Parameter Required Description

api

Yes

The Helix Versioning Engine API level.

path

Yes

A path-like string to a depot or directory that contains other directories or files. Do not include wildcards.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response JSON Body

See Error Conventions for the format of failures.

Ruby Client

See HelixWebServicesClient#delete_file

Helix Versioning Engine Groups

GET /p4/v[api]/groups

Lists available groups in the system. The resources of this list are summaries of groups in the system.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

See Error Conventions for the format of failures.

The values of this method are based on the result of the p4 -ztag groups command. The output of this command is quite a bit different from typical listing queries.

For example, here’s a listing that includes one group with two users:

[
  {
    "user": "mmustermann",
    "group": "test_MUFFUMMY",
    "isSubGroup": "0",
    "isOwner": "0",
    "isUser": "1",
    "maxResults": "0",
    "maxScanRows": "0",
    "maxLockTime": "0",
    "timeout": "43200",
    "passTimeout": "0"
  },
  {
    "user": "super",
    "group": "test_MUFFUMMY",
    "isSubGroup": "0",
    "isOwner": "0",
    "isUser": "1",
    "maxResults": "0",
    "maxScanRows": "0",
    "maxLockTime": "0",
    "timeout": "43200",
    "passTimeout": "0"
  }
]
Ruby Client

See HelixWebServicesClient#groups

POST /p4/v[api]/groups

Creates a new group specification, like the p4 group command.

There are no other parameters to this method.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

Properties of the JSON object are the form fields of the p4 group command.

For example:

{
  "Group": "new_group_id",
  "Users": ["jdoe", "mmustermann"]
}
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#create_group

GET /p4/v[api]/groups/[group]

Return group details, similar to the p4 group -o command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

group

The group name.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Data

Returns the form fields of the p4 -ztag group [group name] command. For more information, see the command reference.

Please note that the way 'unset' is described in this output is different from the listing data.

{
  "Group": "test_MUFFUMMY",
  "MaxResults": "unset",
  "MaxScanRows": "unset",
  "MaxLockTime": "unset",
  "Timeout": "43200",
  "PasswordTimeout": "unset",
  "Users": [
    "mmustermann",
    "super"
  ]
}
Ruby Client

See HelixWebServicesClient#group

PATCH /p4/v[api]/groups/[group]

Update group specifications, similar to the p4 group command. Only the specified parameters in the body will be changed.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

group

The name of the group
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Request Body JSON

A single JSON object containing form fields of the p4 -ztag group [group name] command.

An example updating the list of users:

{
  "Users": ["jdoe", "mmustermann", "saustin"]
}
Ruby Client

See HelixWebServicesClient#update_group

DELETE /p4/v[api]/groups/[group]

Removes the group specification, similar to the p4 group -d command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

group

The name of the group
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#delete_group

Helix Versioning Engine Jobs

GET /p4/v[api]/jobs

Lists available jobs in the system. The resources of this list are summaries of jobs in the system.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

The values of this method are based on the result of the p4 -ztag jobs command. For more field information refer to the command reference.

See Error Conventions for the format of failures.

An example response body might look like:

[
  {
    "Job": "job000001",
    "Status": "open",
    "User": "jdoe",
    "Date": "2015/07/28 13:18:20",
    "Description": "Test Job UVUCBXOS\n"
  }
]
Ruby Client

See HelixWebServicesClient#jobs

POST /p4/v[api]/jobs

Creates a new job specification, like the p4 job command.

There are no other parameters to this method.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

Properties of the JSON object are the form fields of the p4 job command.

For example:

{
  "Job": "new",
  "Description": "A new job for stuff",
  "Status": "open"
}
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#create_job

GET /p4/v[api]/jobs/[job]

Return job details, similar to the p4 job -o command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

job

The job name.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Data

Returns the form fields of the p4 -ztag job [job name] command. For more information, see the command reference. The main difference between the details and list view is the inclusion of the View field.

Example JSON Response
{
  "Job": "job000001",
  "Status": "open",
  "User": "jdoe",
  "Date": "2015/07/28 13:18:20",
  "Description": "Test Job UVUCBXOS\n"
}
Ruby Client

See HelixWebServicesClient#job

PATCH /p4/v[api]/jobs/[job]

Update job specifications, similar to the p4 job command. Only the specified parameters in the body will be changed.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

job

The name of the job
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

A single JSON object containing form fields of the p4 -ztag job [job name] command.

Response Headers
Header Name Notes

Content-Type

application/json
Example JSON Request Body
{
  "Description": "The updated job description.\n"
}
Ruby Client

See HelixWebServicesClient#update_job

DELETE /p4/v[api]/jobs/[job]

Removes the job specification, similar to the p4 job -d command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

job

The name of the job
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#delete_job

Helix Versioning Engine Labels

GET /p4/v[api]/labels

Lists available labels in the system. The resources of this list are summaries of labels in the system.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

The values of this method are based on the result of the p4 -ztag labels command. For more field information refer to the command reference.

See Error Conventions for the format of failures.

An example response body might look like:

[
  {
    "label": "test-label",
    "Update": "1438120994",
    "Access": "1438120994",
    "Owner": "",
    "Options": "unlocked noautoreload",
    "Description": "The label for testing\n"
  }
]
Ruby Client

See HelixWebServicesClient#labels

POST /p4/v[api]/labels

Creates a new label specification, like the p4 label command.

There are no other parameters to this method.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

Properties of the JSON object are the form fields of the p4 label command.

For example:

{
  "Label": "new_label",
  "Description": "A new label for stuff",
  "View": ["//depot/..."]
}
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#create_label

GET /p4/v[api]/labels/[label]

Return label details, similar to the p4 label -o command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

label

The label name.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Data

Returns the form fields of the p4 -ztag label [label name] command. For more information, see the command reference. The main difference between the details and list view is the inclusion of the View field.

Example JSON Response
{
  "Label": "test-label",
  "Update": "2015/07/28 15:03:14",
  "Access": "2015/07/28 15:03:14",
  "Description": "The label for testing\n",
  "Options": "unlocked noautoreload",
  "View": [
    "//depot/..."
  ]
}
Ruby Client

See HelixWebServicesClient#label

PATCH /p4/v[api]/labels/[label]

Update label specifications, similar to the p4 label command. Only the specified parameters in the body will be changed.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

label

The name of the label
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

A single JSON object containing form fields of the p4 -ztag label [label name] command.

Response Headers
Header Name Notes

Content-Type

application/json
Example JSON Request Body
{
  "Description": "The updated new-label description.\n"
}
Ruby Client

See HelixWebServicesClient#update_label

DELETE /p4/v[api]/labels/[label]

Removes the label specification, similar to the p4 label -d command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

label

The name of the label
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#delete_label

Helix Versioning Engine Login

POST /p4/v[api]/login

Generates a host-unlocked Perforce login token for the server.

This is useful in cases where the authentication source is not the same as the p4d instance you operate most operations as. If you happen to have the same authentication source, you can always run this; you’ll pretty much just get the same ticket.

Request Headers
Header Name Notes

Accept

application/json, text/plain

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

A single JSON object with the following keys

Property Description

user

The Helix Versioning Engine login

password

The password for the particular user
Response Headers
Header Name Notes

Content-Type

application/json
Response Body

See Error Conventions for the format of failures.

Example response:

{
  "ticket": "16A76F005802E742E834163A22A4DED4"
}

Helix Versioning Engine Protections

GET /p4/v[api]/protections

Lists available protections in the system. The resources of this list are summaries of protections in the system.

This method likely requires superuser access.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

The values of this method are based on the result of the p4 -ztag protect -o command.

See Error Conventions for the format of failures.

An example response body might look like:

{
  "Protections": [
    "write user * * //...",
    "super user super * //..."
  ]
}
Ruby Client

See HelixWebServicesClient#protections

POST /p4/v[api]/protections

Update the protections table.

This method likely requires superuser access.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

Properties of the JSON object are the form fields of the p4 protect command.

For example:

{
  "Protections": [
    "write user * * //...",
    "super user super * //...",
    "super user jdoe * //..."
  ]
}
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#create_label

Helix Versioning Engine Servers

GET /p4/v[api]/servers

Lists available servers in the system. The resources of this list are summaries of servers in the system.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

The values of this method are based on the result of the p4 -ztag servers command. For more field information refer to the command reference.

See Error Conventions for the format of failures.

An example response body might look like:

[
  {
    "ServerID": "master-1666",
    "Name": "master-1666",
    "Address": "",
    "Type": "server",
    "Services": "commit-server",
    "Description": "Created by su-superuser.\n"
  },
  {
    "ServerID": "buildfarm",
    "Name": "buildfarm",
    "Address": "",
    "Type": "server",
    "Services": "db-read,db-replication,bound-clients,file-replication",
    "Description": "Created by su-superuser.\n"
  }
]
Ruby Client

See HelixWebServicesClient#servers

POST /p4/v[api]/servers

Creates a new server specification, like the p4 server command.

There are no other parameters to this method.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

Properties of the JSON object are the form fields of the p4 server command.

For example:

{
  "ServerID": "new_server",
  "Description": "A new server for stuff",
  "Type": "server",
  "Services": "standard"
}
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#create_server

GET /p4/v[api]/servers/[server]

Return server details, similar to the p4 server -o command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

server

The server name.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Data

Returns the form fields of the p4 -ztag server [server name] command. For more information, see the command reference. The main difference between the details and list view is the inclusion of the View field.

Example JSON Response
{
  "ServerID": "master-1666",
  "Type": "server",
  "Name": "master-1666",
  "Services": "commit-server",
  "Description": "Created by su-jsmith.\n"
}
Ruby Client

See HelixWebServicesClient#server

PATCH /p4/v[api]/servers/[server]

Update server specifications, similar to the p4 server command. Only the specified parameters in the body will be changed.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

server

The name of the server
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

A single JSON object containing form fields of the p4 -ztag server [server name] command.

Response Headers
Header Name Notes

Content-Type

application/json
Example JSON Request Body
{
  "Description": "The updated new-server description.\n"
}
Ruby Client

See HelixWebServicesClient#update_server

DELETE /p4/v[api]/servers/[server]

Removes the server specification, similar to the p4 server -d command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

server

The name of the server
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#delete_server

Helix Versioning Engine Streams

GET /p4/v[api]/streams

Lists available streams in the system. The resources of this list are summaries of streams in the system.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

The values of this method are based on the result of the p4 -ztag streams command. For more field information refer to the command reference.

See Error Conventions for the format of failures.

An example response body might look like:

[
  {
    "Stream": "//stream-test/main-TKOMGMSZ",
    "Update": "1437761647",
    "Access": "1437761647",
    "Owner": "jdoe",
    "Name": "main-TKOMGMSZ",
    "Parent": "none",
    "Type": "mainline",
    "desc": "Test stream main-TKOMGMSZ\n",
    "Options": "allsubmit unlocked notoparent nofromparent",
    "firmerThanParent": "n/a",
    "changeFlowsToParent": "false",
    "changeFlowsFromParent": "false",
    "baseParent": "none"
  }
]
Ruby Client

See HelixWebServicesClient#streams

POST /p4/v[api]/streams

Creates a new stream specification, like the p4 stream command.

There are no other parameters to this method.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

Properties of the JSON object are the form fields of the p4 stream command.

Response Headers
Header Name Notes

Content-Type

application/json
Example Request JSON
{
  "Stream": "//my-stream-depot/main",
  "Name": "my-stream-depot main",
  "Description": "Mainline of MyStream",
  "Type": "mainline",
  "Parent": "none",
  "Paths": ["share ..."],
  "Owner": "jdoe"
}

Ruby Client Example

client.create_stream({
   'Stream' => '//my-stream-depot/main',
   'Name' => 'my-stream-depot main',
   'Description' => "Mainline of MyStream",
   'Type' => 'mainline',
   'Parent' => 'none',
   'Paths' => ['share ...'],
   'Owner' => 'jdoe'
})
Ruby Client

See HelixWebServicesClient#create_stream

GET /p4/v[api]/streams/[stream]

Return stream details, similar to the p4 stream -o command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

stream

The stream path-like identifier, without the leading //
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Data

Returns the form fields of the p4 -ztag stream [stream name] command. For more information, see the command reference. The main difference between the details and list view is the inclusion of the View field.

Example JSON Response
{
  "Stream": "//stream-test/main-TKOMGMSZ",
  "Update": "2015/07/24 11:14:07",
  "Access": "2015/07/24 11:14:07",
  "Owner": "jdoe",
  "Name": "main-TKOMGMSZ",
  "Parent": "none",
  "Type": "mainline",
  "Description": "Test stream main-TKOMGMSZ\n",
  "Options": "allsubmit unlocked notoparent nofromparent",
  "Paths": [
    "share ..."
  ],
  "firmerThanParent": "n/a",
  "baseParent": "none"
}
Ruby Client

See HelixWebServicesClient#stream

PATCH /p4/v[api]/streams/[stream]

Update stream specifications, similar to the p4 stream command. Only the specified parameters in the body will be changed.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

stream

The stream path-like identifier, without the leading //
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

A single JSON object containing form fields of the p4 -ztag stream [stream name] command.

Response Headers
Header Name Notes

Content-Type

application/json
Example JSON Request Body
{
  "Description": "The updated my-project-main description.\n",
  "Owner": "saustin"
}
Ruby Client

See HelixWebServicesClient#update_stream

client.update_stream({
  "Stream" => 'my_stream_id',
  "Description" => "The updated my-project-main description.\n",
  "Owner" => "saustin"
})
DELETE /p4/v[api]/streams/[stream]

Removes the stream specification, similar to the p4 stream -d command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

stream

The stream path-like identifier, without the leading //
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#delete_stream

Helix Versioning Engine Triggers

GET /p4/v[api]/triggers

Lists available triggers in the system. The resources of this list are summaries of triggers in the system.

This method likely requires superuser access.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

The values of this method are based on the result of the p4 -ztag triggers -o command.

See Error Conventions for the format of failures.

An example response body might look like:

{
  "Triggers": [
    "cscheck change-submit //depot/... \"cmd %changelist%\""
  ]
}
Ruby Client

See HelixWebServicesClient#triggers

POST /p4/v[api]/triggers

Update the triggers table.

This method likely requires superuser access.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

Properties of the JSON object are the form fields of the p4 triggers command.

For example:

{
  "Triggers": [
    "cscheck change-submit //depot/... \"cmd %changelist%\""
  ]
}
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#update_triggers

Helix Versioning Engine Users

GET /p4/v[api]/users

Lists available users in the system. The resources of this list are summaries of users in the system.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

The values of this method are based on the result of the p4 -ztag users command. For more field information refer to the command reference.

See Error Conventions for the format of failures.

An example response body might look like:

[
  {
    "User": "jdoe",
    "Update": "1437690307",
    "Access": "1438019139",
    "FullName": "John Doe",
    "Email": "jdoe@example.com",
    "Type": "standard",
    "Password": "enabled"
  },
  {
    "User": "mmustermann",
    "Update": "1437690307",
    "Access": "1437690307",
    "FullName": "Max Mustermann",
    "Email": "max_mower_CTODZMDQ@example.com",
    "Type": "standard",
    "Password": "enabled"
  }
]
Ruby Client

See HelixWebServicesClient#users

POST /p4/v[api]/users

Creates a new user specification, like the p4 user command.

There are no other parameters to this method.

Your server permissions may vary, but this command generally requires super user access.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

Properties of the JSON object are the form fields of the p4 user command.

{
  "User": "new_user",
  "FullName": "New User",
  "Email": "new_user@example.com"
}
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client SDK Usage

See HelixWebServicesClient#create_user

user.create_user({
  "User" => "new_user",
  "FullName" => "New User",
  "Email" => "new_user@example.com"
})

GET /p4/v[api]/users/[user]

Return user details, similar to the p4 user -o command.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

user

The User property of the user specification (i.e., the login string).
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Data

Returns the form fields of the p4 -ztag user [user name] command.

Example JSON response:

{
  "User": "jdoe",
  "Type": "standard",
  "Email": "jdoe@example.com",
  "Update": "2015/07/23 15:25:07",
  "Access": "2015/07/27 10:53:14",
  "FullName": "John Doe",
  "AuthMethod": "perforce",
  "passwordChange": "2015/07/23 15:25:07"
}
Ruby Client

See HelixWebServicesClient#user_details

PATCH /p4/v[api]/users/[user]

Update user specifications, similar to the p4 user command. Only the specified parameters in the body will be changed.

Your server permissions may vary, but this command generally requires super user access to operate on a different user than the authenticated account.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

user

The User property of the user specification (i.e., the login string).
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

A single JSON object containing form fields of the p4 -ztag user [user name] command.

For example, to update the user email:

{
    "Email": "new_email@example.com"
}
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#update_user

user.update_user({
    "Email" => "new_email@example.com"
})
DELETE /p4/v[api]/users/[user]

Removes the user specification, similar to the p4 user -d command.

Your server permissions may vary, but this command generally requires super user access.

Request URL Path Parameters
Parameter Description

api

The Helix Versioning Engine API level.

user

The User property of the user specification (i.e., the login string).
Request Headers
Header Name Notes

Authorization

See Authentication

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Ruby Client

See HelixWebServicesClient#delete_user

Project Methods

These methods provide project JSON defined in Appendix A: Project JSON.

If you are extending Helix Web Services to include your project type, see Adding Project Extensions.

POST /projects/v1/login

Generates a login token for accessing projects via this instance.

This may return a p4 ticket, or another kind of ticket, depending upon the backing implementation. Use of this ticket will generally be used for authenticating requests related to project metadata.

Request Headers
Header Name Notes

Accept

application/json, text/plain

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Request Body JSON

A single JSON object with the following keys

Property Description

user

The Helix Versioning Engine login

password

The password for the particular user
Response Headers
Header Name Notes

Content-Type

application/json, text/plain
Response Body

See Error Conventions for the format of failures.

The response returns a JSON object with a single ticket parameter.

Example response:

{
  "ticket": "16A76F005802E742E834163A22A4DED4"
}

GET /projects/v1

Returns an array of projects accessible to the user.

There are two modes available here: details and ID-only. When details mode is specified, the return value is an array of complete project JSON objects. ID-only mode returns an array of project IDs only.

Request URI Query Parameters
Parameter Key Description Default

mode

details or id. If details, you receive entire project JSON. Otherwise, the output should be an array of strings.

id

extension

Only return projects with the indicated extension type. See the extension ID referenced in Appendix A: Project JSON. When empty, will return all projects.
Request Headers
Header Name Notes

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body JSON

See Error Conventions for the format of failures.

Returns an array of either project IDs, which will be strings, or project JSON. See Appendix A: Project JSON for project JSON details.

Example return of project IDs:

[
    "alpha",
    "beta",
    "gamma",
    "delta"
]

Truncated example return of project JSON:

[
    {
        "id": "alpha",
        "name": "Project Alpha",
        ... truncated
    },
    {
        "id": "beta",
        "name": "Beta Project",
        ... truncated
    }
]

GET /projects/v1/[project]

Returns project details for a particular project.

Request Headers
Header Name Notes

Accept

application/json

Content-Type

application/json

X-Perforce-Helix_Web_Services-*

See Per-Request Configuration
Response Headers
Header Name Notes

Content-Type

application/json
Response Body

See Error Conventions for the format of failures.

Returns the project JSON structure as defined in Appendix A: Project JSON.

Client SDK Reference

For Ruby applications, we produce a helix_web_serivces_client gem that can help adjusting to some of the data inconsistency of our core Helix Versioning Engine.

Server Programming

Including New Rack Middleware

Additional methods can be added as part of the core Helix Web Services server.

Adding new HTTP methods to the API should probably be done in a module specific to your extension, which forms a kind of namespace. By convention, we create a MyModule::App class that inherits from Sinatra::Base, to define the API to your module. Also, by convention, we prefix methods to your module with a simple string path, e.g., my_module.

Say we want the ability to fetch "stuff" from your module. You would create a Sinatra modular app in a my_module/app.rb file:

my_module/app.rb
module MyModule
  class App < Sinatra::Base
     get '/my_module/v1/stuff`
        # We use p4, so make sure you have a p4 connection available
        require_p4

        # If there's a problem, we'll actually handle exceptions for you
        results = env['p4'].run_print('-o', '//depot/stuff')

        # Right now, we only produce JSON.
        results.to_json
     end
  end
end

Typically, you’d reference this in a my_module.rb file, which imports your App, and possibly defines helper methods in your namespace.

my_module.rb
require 'my_module/app'

module MyModule
  def helper_method
    # do something
  end
end

The final step is to include your modular app in the top level HelixWebServices application.

helix_web_services.rb
# ... truncated other things
require 'my_module'

module HelixWebServices
  class Master < Sinatra::Base
    # ... lots of things are truncated

    register_app(MyModule::App)
  end
end

Additionally, a method use_after_settings can run custom middleware after we’ve initialized our per-request configuration.

This will allow you to create special rules that, say, blocks invalid P4PORT values, such that applications can’t use your HWS instance to ping an unexpected perforce instance.

require 'json'

class CustomMiddleware
	def initialize(app)
		@app = app
	end

	def call(env)
	    # Only allow 'localhost:1666' as the P4PORT value
		if env['hws_settings'].P4PORT != 'localhost:1666'
			return [
				400,
	            { 'Content-Type' => 'text/plain',
	              'Content-Length' => '0' },
	            []
		    ]
			raise "localhost:1666 connections only"
		end
		return @app.call(env)
	end
end

HelixWebServices::Master.use_after_settings CustomMiddleware

Registering Configuration Variables

If your application requires new configuration, you should:

  1. Declare your variables in hws_settings.rb

  2. Document your variables in doc/03_configuration.asc

If you follow these steps, your configuration variables will be a part of the env['hws_settings'] hashes available to each Sinatra method.

Adding Project Extensions

A project extension is a combination of JSON metadata and logic that can be used for product-specific integrations, or optional features.

Creating a project extension involves the following tasks:

  1. Define the JSON extension, typically by documenting it

  2. Assign a simple extension ID and versioned MIME-style content type.

  3. Implement logic and assign to callbacks of the ProjectService class

Your extension should probably append handlers to the following methods:

Server API Reference

The Ruby-based server API reference should help you when generating custom services to be deployed into your own environment.

Development Guide

Basic Development Set Up

Helix Web Services runs on Unix-like machines only, typically Linux or OS X. If you want to use Windows, you will likely need to find an alternative for unicorn. Please understand that Windows is currently not tested or supported.

Obtain a copy of the source code from the Perforce Workshop. You can preview the source at https://swarm.workshop.perforce.com/projects/perforce-software-helix-web-services. If you have an account, you can import the code from //guest/perforce_software/helix-web-services/main/…​ into your workspace.

From there you will need:

  1. A recent version of Ruby, Ruby 2.2+ from RVM is recommended.

  2. Bundler, typically installed via gem install bundler.

First, you’ll setup a p4d instance locally that’s been seeded with some test data.

cd helix_web_services_client
bundle install
bundle exec p4util start
bundle exec p4util init
cd ..

(You can shut this server down with the command bundle exec p4util kill when you’re done.)

Next, you’ll launch Helix Web Services running under Unicorn, via the Foreman command:

cd helix_web_services
bundle install
WORKSPACE_DIR=/tmp/clients bundle exec foreman start

In case you need methods that generate temporary client workspaces, you’ll need the environment variable set. If you don’t set it, it will likely go to a default directory you do not

This should launch the application in the foreground. Use CTRL+C to kill it. This mechanism does not automatically reload all changes.

Helix Web Services is a fairly simple Sinatra Rack application. It’s entirely possible to launch it via a debugger under a different application server. This is typically done in IDEs such as RubyMine. Use the config.ru file in the helix_web_services directory and set the WORKSPACE_DIR environment variable.

Running some tests

Executing tests like we do for automated builds is easy:

rake test

But, this is probably not what you want. This will create HTML output files. And it will start up both p4d and unicorn, then shut them both down.

For your development system, you probably want to have this environment:

  1. The web server is running in a debugger

  2. The p4d instance is hanging around

  3. You can launch client or server tests independently

Since I’m a RubyMine user, steps 1 and 3 are done via the IDE. Step 2, however, is done by a basic utility function called p4util, which I’ll describe in the next section.

Setting up RubyMine to runthe webserver requires these steps:

  1. Create a new "Rack" configuration, and set the config file to helix_web_services/config.ru.

  2. Change the port to 9000.

  3. Set the WORKSPACE_DIR environment variable to something writable like /tmp/workspaces.

Setting up RubyMine to launch tests is similarly straightforward:

  1. Create a new "RSpec" configuration

  2. Set the specs folder to helix_web_services_client/spec or helix_web_services/spec

Setting up a test p4d locally with p4util

The complete calling sequence to reset a test p4d locally is to run these commands in the root if the source tree:

p4util kill
rm -rf /tmp/p4util/p4droot
p4util start
p4util init data/p4init

I typically execute this sequence in my bash shell using the && operator:

p4util kill && rm -rf /tmp/p4util/p4droot && p4util start && p4util init data/p4init

This will reset.

Using the hws_console against a development mode server

An hws_console application is available for local use, which can be useful for trying out a few commands. Launch it under bundler:

cd helix_web_services
bundle exec ./bin/hws_console

This will create a basic PRY interactive console.

To create a client instance, you will typically run:

c = HelixWebServicesClient.new(url: 'http://localhost:9000', user: 'jdoe', password: 'johndoe1A!')

From there, c is a client instance, you can use to run commands.

# Print the list of depot names as a string
c.depots.map(&:name).join(", ")

Adding custom logic to your HWS installation

Some custom logic can be used to add or modify functionality of HWS. The CUSTOM_SCRIPTS property - see Configuration - points to a directory. If this directory exists, any ruby files will be required after most of the core application has been installed. This is a way to include some logic into the HWS system.

Here’s an example custom Ruby script adding methods to HWS via a new Sinatra module:

require 'sinatra/base'

class MyApp < Sinatra::Base

	get '/my_app' do
		{'custom': true}.to_json
	end
end

HelixWebServices::Master.register_app(MyApp)

Appendices

Appendix A: Project JSON

Projects relate branches of revisions with other structures, like groups, to help create the foundation for general workflows.

The content type of the project JSON is application/vnd.perforce.project.v1+json. You can specify the content type without the version string, e.g., application/vnd.perforce.project+json. This may be useful in cases where you can handle possibly different versions of JSON, say, for migration.

JSON structure

A project document is a JSON object that contains the following properties.

Property Required Description

id

Yes

The id should be a unique string. It should be safe to put in as a single path element in a URI.

name

Yes

A string suitable for display of the project.

server

Yes

A P4 URL that indicates how to connect to the p4d instance to retrieve the files of the project. For example, p4://P4CHARSET=auto@perforce.myinstance.com:1666

Extension ID

No

Each extension ID will map to a particular JSON object type defined for each extension. For example, there may be a property named helixCloud that maps to the JSON defined in Appendix C: Helix Cloud.

Project Extensions

Each project extension should have a simple string ID, e.g., helixCloud, gitFusion.

Project extensions should always define a contentType property that is a versioned MIME content type. For example, application/vnd.perforce.helixCloud.v1+json.

Appendix B: Helix Versioning Engine Project JSON

Returns projects that are stored in a single Helix Versioning Engine server.

If the HVE_PROJECT_PATH setting is specified, this will return all directories under that path as projects. The project id is encoded to be a specific part of a URL. It is the application’s responsibility to deal with any reconfiguration of the HVE_PROJECT_PATH setting. The project id is only valid for the same setting.

The project name is also the name of the directory, just not URL-safe.

The server property will include the HVE_PROJECT_PATH setting as the URL path.

The content type of this JSON is application/vnd.perforce.project.hve.v1+json. The simple string ID is hve.

JSON Structure

Property Required Description

depotPath

Yes

The absolute depot path to the folder on the server.

Appendix C: Helix Cloud

Warning
 We do not yet know the JSON structure from Helix Cloud, and exactly what it will need to provide to the Helix Sync client.

Appendix D: Service Configuration JSON

JSON Structure

A service configuration document is a JSON array of objects. Each object contains the following properties:

Property Type

Description

type

String

The type of service available in the system. One of p4d, git-swarm, git-fusion, swarm, or commons.

uri

Array

Stored Format

The service configuration JSON is a file pointed to by the SERVICE_CONFIGURATION variable. See Configuration for details.

It is assumed that the configuration is maintained by the system administrator. Edits to files should be coordinated across all HWS instances.