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:
-
Nginx: http://nginx.org/
-
Unicorn: http://unicorn.bogomips.org/
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:
-
Product overview: http://www.perforce.com/versioning-engine
-
P4 Command Reference: http://www.perforce.com/perforce/doc.current/manuals/cmdref/index.html
-
Admin fundamentals: http://www.perforce.com/perforce/doc.current/manuals/p4sag/index.html
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:
-
Ruby 2.2
-
An installed Perforce server
Other Ruby variations will likely work, we do not test them.
Installation steps:
-
Run:
tar xzf helix-web-services-[VERSION].tar.gz -
Run:
cd helix-web-services-[VERSION]/helix_web_services -
Run:
bundle install -
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
helixwebservicesaccount 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 |
|
Will not be created if already exists |
Create directory for logging data, assign to user account |
|
Will not be created if already exists |
Link upstart configuration |
|
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 |
For details of the steps taken, review the script code online at:
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 |
|---|---|---|---|---|
|
Array |
No |
Allows access to run commands via |
|
|
String |
No |
The local directory that will load up user defined Ruby scripts. |
/var/lib/perforce/helix_web_services/scripts |
|
Boolean |
No |
Use Helix Cloud as the authentication source. |
false |
|
Boolean |
No |
Enable Helix Cloud as a project source. |
false |
|
String |
Yes |
The depot location in the Helix Versioning Engine that hosts all projects in that server. |
|
|
String |
Yes |
The hostname for the perforce server, e.g., |
|
|
String |
Yes |
The port number (or port and hostname combination) that indicates our Perforce connection |
|
|
String |
Yes |
The charset value for P4 connections.
Set to |
|
|
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. |
|
|
String |
No |
Local file location that defines how services are to be configured. |
|
|
String |
No |
The local directory used for generating temporary Perforce Client Workspaces to do some basic operations. |
|
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 |
|---|---|
|
A numeric ID for the problem, typically defined by the Helix Versioning Engine. Should be the same value as Error::GetGeneric(). |
|
Mirrors the severity levels of Error::GetSeverity(). Generally going to be 3 or 4. |
|
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:
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, '/helix_versioning_engine/v[api]/files')
# Print depot names
depots.each { |d| puts d['name'] }
# Make a user
client.execute_method_with_body(:post, '/helix_versioning_engine/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.
Authentication Methods
Configuration Methods
Git Fusion Methods
Repositories
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
Authentication Methods
POST /auth/v1/login
Generates the Perforce login token for the server.
Request Headers
| Header Name | Notes |
|---|---|
|
|
|
|
|
Request Body JSON
A single JSON object with the following keys
| Property | Description |
|---|---|
|
The Helix Versioning Engine login |
|
The password for the particular user |
Response Headers
| Header Name | Notes |
|---|---|
|
|
Response Body
See Error Conventions for the format of failures.
Upon success, when Content-Type is text/plain, the response body is simply the P4 ticket value.
16A76F005802E742E834163A22A4DED4
When Content-Type is application/json, the response is a JSON object.
{
"ticket": "16A76F005802E742E834163A22A4DED4"
}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 |
|---|---|
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}
]Git Fusion Repositories
GET /git_fusion/v1/repos
|
Warning
|
Not implemented |
Return the list of repositories readable by the current user.
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
Response Body JSON
|
Tip
|
This is likely a JSON conversion of the Python config format. |
POST /git_fusion/v1/repos
|
Warning
|
Not implemented |
Create a new repository configuration.
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Request JSON Body
|
Tip
|
This is likely a JSON conversion of the Python config format. |
Response Headers
| Header Name | Notes |
|---|---|
|
|
GET /git_fusion/v1/repos/[repo]
|
Warning
|
Not implemented |
Return the list of repositories readable by the current user.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The repository name |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
Response Body JSON
|
Tip
|
This is likely a JSON conversion of the Python config format. |
PUT /git_fusion/v1/repos/[repo]
|
Warning
|
Not implemented |
Replce the repository configuration.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The repository name |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Request JSON Body
|
Tip
|
This is likely a JSON conversion of the Python config format. |
Response Headers
| Header Name | Notes |
|---|---|
|
|
PATCH /git_fusion/v1/repos_repo
|
Warning
|
Not implemented |
Update values in the repository configuration.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The repository name |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Request JSON Body
|
Tip
|
This is likely a JSON conversion of the Python config format. |
Response Headers
| Header Name | Notes |
|---|---|
|
|
DELETE /git_fusion/v1/repos_repo
|
Warning
|
Not implemented |
Delete the repository configuration.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The repository name |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Request JSON Body
|
Tip
|
This is likely a JSON conversion of the Python config format. |
Helix Sync Changes
Many operations for Helix Sync are related to manipulating changelists in order to share state across devices.
GET /helix_sync/v1/changes/[project]
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 |
|---|---|
|
The project ID, see Appendix A: Project JSON |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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.
POST /helix_sync/v1/changes/[project]
Request to create a changelist for the user and [project] to be used as a shared shelf amongst devices. This is a no-op if no such changelist currently exists, and the existing change will be returned.
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 |
|---|---|
|
The project ID, see Appendix A: Project JSON |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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/changes/[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.
Will return a 404 (not found) if such a changelist does not exist.
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 |
|---|---|
|
The project ID, see Appendix A: Project JSON |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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.
POST /helix_sync/v1/changes/[project]/pending
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 |
|---|---|
|
The project ID, see Appendix A: Project JSON |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
Response Body JSON
See Error Conventions for the format of failures.
Helix Sync Clients
POST /helix_sync/v1/clients
Creates a new client workspace for use by helix sync.
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 Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Request Body JSON
Requires a JSON object with the following parameters:
| Property | Description |
|---|---|
|
The project ID, see Appendix A: Project JSON |
|
A unique ID for the device in use. |
|
The directory path on the user’s machine to use. |
Response Headers
| Header Name | Notes |
|---|---|
|
|
Response Body JSON
Returns a JSON object with a client property, indicating the client name to use.
Helix Versioning Engine Branches
GET /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}
]POST /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
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 |
|---|---|
|
|
GET /helix_versioning_engine/v[api]/branches/[branch]
Return branch details, similar to the p4 branch -o command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
branch |
The branch name. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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/..."
]
}PATCH /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
branch |
The name of the branch |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Request Body JSON
A single JSON object containing form fields of the p4 -ztag branch [branch name] command.
Response Headers
| Header Name | Notes |
|---|---|
|
|
Example JSON Request Body
{
"Description": "The updated my-project-main description.\n",
"Owner": "saustin"
}Ruby Client
client.update_branch({
"Branch" => 'my_branch_id',
"Description" => "The updated my-project-main description.\n",
"Owner" => "saustin"
})DELETE /helix_versioning_engine/v[api]/branches/[branch]
Removes the branch specification, similar to the p4 branch -d command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
branch |
The name of the branch |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
Helix Versioning Engine Changes
GET /helix_versioning_engine/v[api]/changes
List changelist summaries, with some common filtering options.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
Request URI Query Parameters
The following parameters are all optional.
| Key | Description |
|---|---|
|
Limits the number of results returned See the changes -m option. |
|
Only return results with the indicated status. See the changes -s option. |
|
Only return changes owned by this particular user. See the changes -u option. |
|
Limit changes to the depot path expressions. See the changes command description. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}
]POST /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Request JSON Body
The request should be a JSON object with the following properties:
| Parameter | Description | Type | Parameter Type | Required |
|---|---|---|---|---|
|
Textual description of the change |
string |
body |
No |
|
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 |
|---|---|---|
|
The depot path specifier for the action |
Yes |
|
When the Action is a branch or move, this indicates the source of the operation. |
No |
|
One of |
Yes |
|
If the Action is upload, this is the base-64 encoded file content. |
No |
|
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 |
|---|---|
|
|
Response JSON
See Error Conventions for the format of failures.
GET /helix_versioning_engine/v[api]/changes/[change]
Read details of a single changelist in the system.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
change |
The changelist number. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
]
}
]POST /helix_versioning_engine/v[api]/changes/[change]
Submit shelved changes to the depot.
Uses the p4 submit -e command to perform the submit.
This method will fail:
-
If the changelist in question is not a pending changelist with a shelf.
-
If any resolves are required.
-
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 |
|---|---|
|
The Helix Versioning Engine API level. |
change |
The changelist number. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
Response JSON Body
See Error Conventions for the format of failures.
Helix Versioning Engine Clients
GET /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}
]POST /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Request Body JSON
Properties of the JSON object are the form fields of the p4 client command.
Response Headers
| Header Name | Notes |
|---|---|
|
|
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/..."]
})GET /helix_versioning_engine/v[api]/clients/[client]
Return client details, similar to the p4 client -o command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
client |
The client name. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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/..."
]
}PATCH /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
client |
The client name. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Request Body JSON
A single JSON object containing form fields of the p4 -ztag client [client name] command.
Response Headers
| Header Name | Notes |
|---|---|
|
|
Example JSON Request Body
{
"Options": "allwrite noclobber nocompress unlocked nomodtime rmdir"
}Ruby Client
client.update_client({
"Options" => "noallwrite noclobber nocompress unlocked nomodtime normdir"
})DELETE /helix_versioning_engine/v[api]/clients/[client]
Removes the client specification, similar to the p4 client -d command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
client |
The client name. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
Helix Versioning Engine Commands
GET /helix_versioning_engine/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 |
|---|---|---|
|
Yes |
The Helix Versioning Engine API level. |
|
Yes |
The command name, that should be whitelisted in the system configuration. See Configuration. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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.
POST /helix_versioning_engine/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 |
|---|---|---|
|
Yes |
The Helix Versioning Engine API level. |
|
Yes |
The command name, that should be whitelisted in the system configuration. See Configuration. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
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 |
|---|---|
|
|
Response Body JSON
See Error Conventions for the format of failures.
Helix Versioning Engine Counters
GET /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}
]GET /helix_versioning_engine/v[api]/counters/[counter]
Return counter details, similar to the p4 counter command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
counter |
The counter name. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}PUT /helix_versioning_engine/v[api]/counters/[counter]
Sets a counter, like the p4 counter [counter] [value] command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
counter |
The counter name. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Request Body JSON
The request body is a JSON object with a value property.
For example:
{
"value": "123"
}Response Headers
| Header Name | Notes |
|---|---|
|
|
POST /helix_versioning_engine/v[api]/counters/[counter]/increment
Increments a numerical counter, similar to the p4 counter -i command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
counter |
The name of the counter |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
DELETE /helix_versioning_engine/v[api]/counters/[counter]
Removes the counter specification, similar to the p4 counter -d command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
counter |
The name of the counter |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
Helix Versioning Engine Depots
GET /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}
]POST /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
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 |
|---|---|
|
|
GET /helix_versioning_engine/v[api]/depots/[depot]
Return depot details, similar to the p4 depot -o command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
depot |
The depot name. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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/..."
}PATCH /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
depot |
The name of the depot |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Request Body JSON
A single JSON object containing form fields of the p4 -ztag depot [depot name] command.
Response Headers
| Header Name | Notes |
|---|---|
|
|
Example JSON Request Body
{
"Description": "The updated new-depot description.\n"
}DELETE /helix_versioning_engine/v[api]/depots/[depot]
Removes the depot specification, similar to the p4 depot -d command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
depot |
The name of the depot |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
Helix Versioning Engine Files
GET /helix_versioning_engine/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 |
|---|---|---|
|
Yes |
The Helix Versioning Engine API level. |
|
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 |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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
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 /helix_versioning_engine/v[api]/files/[path]
Provides a means for uploading content to a particular file or directory.
This is a simplification of the POST /helix_versioning_engine/v[api]/changes method, where action is always upload on all files.
Request URL Path Parameters
| Parameter | Required | Description |
|---|---|---|
|
Yes |
The Helix Versioning Engine API level. |
|
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 |
|---|---|
|
See Authentication |
|
|
|
|
|
Request JSON Body
The Request JSON is an object with the following top-level parameters:
| Property | Required | Description |
|---|---|---|
|
No |
A text field describing the new file changes |
|
No |
For multiple files, this is an array of objects, each containing the same |
|
No |
If this is a single file upload, this is the file path, relative to the |
|
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 |
|---|---|
|
|
Response JSON Body
See Error Conventions for the format of failures.
DELETE /helix_versioning_engine/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 |
|---|---|---|
|
Yes |
The Helix Versioning Engine API level. |
|
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 |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
Response JSON Body
See Error Conventions for the format of failures.
Helix Versioning Engine Groups
GET /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}
]POST /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
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 |
|---|---|
|
|
GET /helix_versioning_engine/v[api]/groups/[group]
Return group details, similar to the p4 group -o command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
group |
The group name. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
]
}PATCH /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
group |
The name of the group |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"]
}DELETE /helix_versioning_engine/v[api]/groups/[group]
Removes the group specification, similar to the p4 group -d command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
group |
The name of the group |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
Helix Versioning Engine Jobs
GET /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}
]POST /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
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 |
|---|---|
|
|
GET /helix_versioning_engine/v[api]/jobs/[job]
Return job details, similar to the p4 job -o command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
job |
The job name. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}PATCH /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
job |
The name of the job |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Request Body JSON
A single JSON object containing form fields of the p4 -ztag job [job name] command.
Response Headers
| Header Name | Notes |
|---|---|
|
|
Example JSON Request Body
{
"Description": "The updated job description.\n"
}DELETE /helix_versioning_engine/v[api]/jobs/[job]
Removes the job specification, similar to the p4 job -d command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
job |
The name of the job |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
Helix Versioning Engine Labels
GET /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}
]POST /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
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 |
|---|---|
|
|
GET /helix_versioning_engine/v[api]/labels/[label]
Return label details, similar to the p4 label -o command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
|
The label name. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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/..."
]
}PATCH /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
|
The name of the label |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Request Body JSON
A single JSON object containing form fields of the p4 -ztag label [label name] command.
Response Headers
| Header Name | Notes |
|---|---|
|
|
Example JSON Request Body
{
"Description": "The updated new-label description.\n"
}DELETE /helix_versioning_engine/v[api]/labels/[label]
Removes the label specification, similar to the p4 label -d command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
|
The name of the label |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
Helix Versioning Engine Login
POST /helix_versioning_engine/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 |
|---|---|
|
|
|
|
|
Request Body JSON
A single JSON object with the following keys
| Property | Description |
|---|---|
|
The Helix Versioning Engine login |
|
The password for the particular user |
Response Headers
| Header Name | Notes |
|---|---|
|
|
Response Body
See Error Conventions for the format of failures.
Example response:
{
"ticket": "16A76F005802E742E834163A22A4DED4"
}Helix Versioning Engine Protections
GET /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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 * //..."
]
}POST /helix_versioning_engine/v[api]/protections
Update the protections table.
This method likely requires superuser access.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
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 |
|---|---|
|
|
Helix Versioning Engine Servers
GET /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}
]POST /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
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 |
|---|---|
|
|
GET /helix_versioning_engine/v[api]/servers/[server]
Return server details, similar to the p4 server -o command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
server |
The server name. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}PATCH /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
server |
The name of the server |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Request Body JSON
A single JSON object containing form fields of the p4 -ztag server [server name] command.
Response Headers
| Header Name | Notes |
|---|---|
|
|
Example JSON Request Body
{
"Description": "The updated new-server description.\n"
}DELETE /helix_versioning_engine/v[api]/servers/[server]
Removes the server specification, similar to the p4 server -d command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
server |
The name of the server |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
Helix Versioning Engine Streams
GET /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}
]POST /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Request Body JSON
Properties of the JSON object are the form fields of the p4 stream command.
Response Headers
| Header Name | Notes |
|---|---|
|
|
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'
})GET /helix_versioning_engine/v[api]/streams/[stream]
Return stream details, similar to the p4 stream -o command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
stream |
The stream path-like identifier, without the leading |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}PATCH /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
stream |
The stream path-like identifier, without the leading |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Request Body JSON
A single JSON object containing form fields of the p4 -ztag stream [stream name] command.
Response Headers
| Header Name | Notes |
|---|---|
|
|
Example JSON Request Body
{
"Description": "The updated my-project-main description.\n",
"Owner": "saustin"
}Ruby Client
client.update_stream({
"Stream" => 'my_stream_id',
"Description" => "The updated my-project-main description.\n",
"Owner" => "saustin"
})DELETE /helix_versioning_engine/v[api]/streams/[stream]
Removes the stream specification, similar to the p4 stream -d command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
stream |
The stream path-like identifier, without the leading |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
Helix Versioning Engine Triggers
GET /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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%\""
]
}POST /helix_versioning_engine/v[api]/triggers
Update the triggers table.
This method likely requires superuser access.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
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 |
|---|---|
|
|
Helix Versioning Engine Users
GET /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}
]POST /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
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 |
|---|---|
|
|
Ruby Client SDK Usage
user.create_user({
"User" => "new_user",
"FullName" => "New User",
"Email" => "new_user@example.com"
})GET /helix_versioning_engine/v[api]/users/[user]
Return user details, similar to the p4 user -o command.
Request URL Path Parameters
| Parameter | Description |
|---|---|
|
The Helix Versioning Engine API level. |
user |
The |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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"
}PATCH /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
user |
The |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
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 |
|---|---|
|
|
Ruby Client
user.update_user({
"Email" => "new_email@example.com"
})DELETE /helix_versioning_engine/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 |
|---|---|
|
The Helix Versioning Engine API level. |
user |
The |
Request Headers
| Header Name | Notes |
|---|---|
|
See Authentication |
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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.
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 |
|---|---|---|
|
|
|
|
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 |
|---|---|
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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 |
|---|---|
|
|
|
|
|
Response Headers
| Header Name | Notes |
|---|---|
|
|
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:
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
endTypically, you’d reference this in a my_module.rb file, which imports your App, and possibly defines helper methods in your namespace.
require 'my_module/app'
module MyModule
def helper_method
# do something
end
endThe final step is to include your modular app in the top level HelixWebServices application.
# ... truncated other things
require 'my_module'
module HelixWebServices
class Master < Sinatra::Base
# ... lots of things are truncated
register_app(MyModule::App)
end
endRegistering Configuration Variables
If your application requires new configuration, you should:
-
Declare your variables in
hws_settings.rb -
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:
-
Define the JSON extension, typically by documenting it
-
Assign a simple extension ID and versioned MIME-style content type.
-
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:
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.
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 |
|---|---|---|
|
Yes |
The |
|
Yes |
A string suitable for display of the project. |
|
Yes |
A P4 URL that indicates how to connect to the p4d instance to retrieve the files of the project.
For example, |
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 |
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 |
|---|---|---|
|
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 |
|
String |
The type of service available in the system.
One of |
|
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.