# Soy API

Bitbucket Server exposes a Soy ([Closure Templates](https://developers.google.com/closure/templates/?csw=1)) API that you 
can use to add widgets to your pages.

Currently the Bitbucket team only supports a single template as API. That component is the [bitbucket.component.branchSelector.field](./soy/branch-selector-field.html) template and is primarily meant for use in [Repository Hook](../how-tos/repository-hooks.html) configuration forms.
No Web Resource dependency is required to use it from a configuration form, however if it is to be used elsewhere you must depend on the
appropriate web resource module.  See the template documentation for more details.

## Compatibility Policy

The Soy API's compatibility policy matches that of Bitbucket's other APIs. Soy APIs will not contain breaking changes between
minor versions (e.g. 4.0 and 4.1). Instead, any removed or modified templates and parameters will have a `'deprecated'`
CSS class added to their output HTML when used, and the legacy behavior will cease to work in the next major release (e.g. Bitbucket Server 5.0).

"Breaking changes" describes removal of templates or template parameters, or changes to accepted template parameter values
that would cause previously valid input to generate invalid HTML, or throw an error. Behavior for _invalid_ inputs may change
at any release, and mutation of Soy templates is not supported. See [API Scope](#API_Scope) for details.

## Loading the APIs

Soy APIs are not guaranteed to be available on the page. Before using an API you **MUST** depend on the matching web-resource
module for that API. Look at the documentation for a template to determine the dependency required. See the [Web Resource Plugin Module](https://developer.atlassian.com/display/DOCS/Web+Resource+Plugin+Module) documentation for details about how they work.

## API Scope

### Templates

The scope of the Soy API is limited to the Soy namespaces of `bitbucket.component.*` and `aui.*`. The stability of any other Soy
templates is not guaranteed between minor versions.

For any template under that namespace, we guarantee that the template will continue to exist across minor versions. New
templates may also be added between minor versions.

### Parameters

If a template parameter is listed as optional it is not required and won't become a required parameter between versions.

If a parameter name ends in `Content`, then it expects valid, pre-escaped HTML strings as the value. You should not pass raw strings into these parameters,
especially if they come from user input, as this would create a security vulnerability in Bitbucket.

### Explicitly out of scope

The markup generated by the Bitbucket templates is explicitly undefined and unstable. You **MUST NOT** rely on the shape of that markup,
except through CSS classes and IDs you have explicitly defined through the `extraClasses` and `id` parameters to the template.

The version of Closure Templates used in Bitbucket **MAY** change. We will make a best-effort attempt not to introduce breaking
changes through upgrades to Closure Templates.