01_overview.asc #3

== Overview

Helix Web Services, or HWS, is a middleware platform for Perforce technologies in the Helix ecosystem.
HWS forms a central point for applications to communicate and coordinate across service applications installed in a single cluster.
While HWS does contain significant logic, it is an extension to other technologies, and is unlikely to be used in isolation.

=== Knowledge Required

For installing or configuring an HWS instance, you should be familiar with common system administration tasks and conventions.
To develop applications against HWS, we assume you are familiar with the HTTP protocol.
We do provide some basic client API libraries, but these are to assist in making it easy to get started, not to abstract away or hide the fundamentals of the HTTP-based system.

To secure your HWS instances, you will need to be comfortable with TLS certificates.
Helix Web Services recommends using HTTPS for connections, unless you can secure access to the server by other means.
For evaluation, we do simplify the process of using a self-signed certificate.
However, for production, it is recommended you purchase and deploy a properly signed certificate.

Additionally, because this guide interfaces with the Helix Versioning Engine, we assume you are familiar with it.
For more information about the Helix Versioning Engine, consult 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

===  Release compatibility of the API

The major and minor version of Helix Web Services is associated with a major release of the Helix Versioning Engine (p4d).
For example, the version 2016.1.0 is associated with the 2016.1 release of p4d, and what we recommend to deploy.
The APIs that you develop against will use data documented as if this was your runtime system.

The Helix Web Services APIs are split into default, or stable, methods and unstable alpha methods.
Methods that are stable should work against future releases of Helix Web Services, for (at least) the next 3 major releases.
A major release is when we update the major or minor version, e.g., 2016.2.0 is the next major release after 2016.1.0.
That is, a client application written against 2016.1.0 can use that SDK against Helix Web Services releases 2016.2.0, 2017.1.0, and 2017.2.0.
Unstable methods may stop working with an upgrade, so planning and testing is required if you put these methods into use.
If you use our SDKs, the use of alpha methods is quite explicit, so generally easy to track.

You can use Helix Web Services against older versions of the Helix Versioning Engine, even though the API was developed against a newer release.
In these cases, the entire API is not guaranteed to exist, and you will need to test your applications against these server configurations.
Some fields may be missing, and some behaviors may change subtly.
In general, however, we try to assist in making these scenarios possible, and do not explicitly break with older versions of p4d.
It's recommended to set the `P4APILEVEL` setting for each server, or globally to the oldest version in use.
See <<settings>> for more details on server configuration.