Application properties

Application properties provide a way for Connect apps to store data inside Bitbucket, as if it were a key/value store. We support storing properties against repositories, users, pull requests, and commits. Properties stored against other object types will likely be supported in the future.

The URL for fetching a property value looks like this:

1
2
GET https://api.bitbucket.org/2.0/repositories/<account>/<repository>/properties/<app key>/<property>

In this example, account is the account where the app is installed, repository is the repository against which the property is stored, app key is the key of the application, and property is the name of the property.

Set a property value with this URL:

1
2
PUT https://api.bitbucket.org/2.0/repositories/<account>/<repository>/properties/<app key>/<property>

{
  "foo": "bar",
  "abc": "def",
  "enabled": true
}

All the placeholders in this PUT example are the same as for the GET example, additionally there is a JSON body containing the value being set for the property. The structure of the body is largely defined by the caller. There are a couple of important notes:

1. The keys of any JSON object must match the regular expression ^[-_a-zA-Z0-9]+$.
2. The _attributes value at the top level can be used to control who can read and write the variable. For details, see Attributes.

There is a corresponding DELETE method available to remove properties that were previously set:

1
2
DELETE https://api.bitbucket.org/2.0/repositories/<account>/<repository>/properties/<app key>/<property>

Authentication

To GET a property, any valid Bitbucket API authentication type may be used (see this page and this page for ways to authenticate requests to Bitbucket). A property may not be visible to requests signed with certain kinds of auth depending on the property attributes (explained below).

To PUT or DELETE a property, requests may always be made using a JWT token. Additionally, they may sometimes be made from the app client in the browser using the AP.require('request', ...) pattern. The situations where it is appropriate to call the mutative methods from the browser are described in the following section on Attributes.

Attributes

When you create a property value you can set attributes for it, like this:

1
2
PUT https://api.bitbucket.org/2.0/repositories/<account>/<repository>/properties/<app key>/<property>

{
  'foo': 'bar',
  '_attributes': [
    'read_only',
    'public'
  ]
}

The two supported attributes are read_only and public.

Properties with the read_only attribute are only able to be set or removed using JWT authentication. This provides a way for apps to set values that cannot be tampered with by an end user that invokes an AP.require('request', ...) call to the properties API from the browser. This way, an app knows that it is the only one that has mutated these values, which could be handy if the property is being used to enforce security controls. Properties without this attribute may also be mutated via calls to AP.require('request', ...) from the browser.

Properties with public attribute may be queried by callers other than the app, providing a way for apps to share non-sensitive information externally with others. If this attribute is not present, a property may only be queried by the app that created it, either with a JWT-signed request or via the AP.require('request', ...) API called from the app browser client.

Using properties in descriptor URLs

It is possible to refer to application properties in the app descriptor to include the value of an application property in the url field of modules, such as in the following example:

1
2
"modules": {
  "repoPages": [
    {
      "url": "/home?userProperty={user.properties.get(attribute=app.key).myproperty.enabled}",
      "name": {
        "value": "Home page"
      },
      "location": "org.bitbucket.repository.navigation",
      "key": "home",
    }
  ]
}

Using properties in descriptor conditions

It is also possible to refer to application properties in the app descriptor conditions to configure the conditional render logic of a module, such as in the following example:

1
2
"conditions": [{
  "type": "or",
  "conditions": [{
    "condition": "property_exists",
    "target": "repository.properties",
    "params": {
      "appKey": {
        "eval": "app.key"
      },
      "propertyKey": "myproperty",
      "objectName": "enabled"
    },
    "invert": true
  },
  {
    "condition": "equals",
    "target": "repository.properties.get(attribute=app.key).myproperty.enabled",
    "params": {
      "value": "true"
    }
  }]
}]

In this example of a module conditions block the module is only rendered if either the property myproperty has not been set, or if has been set to the value:

1
2
{
  'enabled': true
}

If it has been set to the value:

1
2
{
  'enabled': false
}

or any other value for enabled other than true, the module will not be shown in the UI for this account/repository.

Accessing property values via the API

Another cool thing you can do is request that repository properties be returned in API responses that are returning Bitbucket repositories. To request properties are attached to an API response you can do:

1
2
curl -G -u <user>:<app password> https://api.bitbucket.org/2.0/repositories/<account>/<repository> \
--data-urlencode 'fields=+properties.*'

If you have property values containing nested objects you'd like returned in the response, you will need to appropriately specify the depth of the inclusion of properties field (for example, fields=+properties.*.*.*).

Note, non-public properties will only be visible to requests signed with a JWT token crafted by the app, or if an app makes requests using AP.require('request', ...) from within a connect iframe. Public properties can be accessed via the API by any requests that have permission to access the repository.

When retrieving application properties in this manner, you are limited to a maximum of 100 properties in the repsonse.