01_overview.asc #1

== 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.