Bloomreach Cloud API
API that drives the Bloomreach Cloud platform
Resource Group ¶
Authentication ¶
All authentication related endpoints
LoginPOST/v3/authn/access_token
Create a JWT access token from the submitted credentials.
Token lifetimes:
-
The access token is valid for 10 minutes.
-
The refresh token is valid for 24 hours.
Example URI
Headers
Content-Type: application/json; charset=utf-8
Body
{
"username": [your-username],
"password": [your-password]
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"token_type": "bearer",
"access_token": [jwt-token]
"refresh_token": [refresh-token]
}
401
Headers
Content-Type: application/json; charset=utf-8
Body
{
"error_code": "AuthenticationFailed",
"error_detail": [detail message]
}
Validate access tokenGET/v3/authn/verify_token
Example URI
Headers
Content-Type: application/json; charset=utf-8
Authorization: bearer 5262d64b892e8d4341000001
200
Headers
X-User-Id: [ user-id ]
X-User-Role: [ user-role ]
401
Generate new access token from refresh tokenPOST/v3/authn/refresh_token
Example URI
Headers
Content-Type: application/json; charset=utf-8
Body
{
"grant_type": "refresh_token",
"refresh_token": [your-refresh-token]
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"token_type": "bearer",
"access_token": [jwt-token]
}
401
Delete refresh tokenDELETE/v3/authn/refresh_token
Example URI
Headers
Content-Type: application/json; charset=utf-8
Body
{
"grant_type": "refresh_token",
"refresh_token": [your-refresh-token]
}
200
Headers
Content-Type: application/json; charset=utf-8
LogoutPOST/v3/authn/logout
Logout user by invalidating all user’s access tokens
Example URI
Headers
Authorization: [ access token ]
200
401
Distributions ¶
Handles the distribution file operations
List distributionsGET/v3/distributions
List distribution files
Example URI
Headers
Authorization: Bearer [ authentication token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"offset": 0,
"max": 100,
"count": 6,
"more": false,
"total": 6,
"items": [
{
"id": "4B36A01A8EBA74B7",
"name": "cms-4.1.0-distribution.tar.gz",
"createdAt": "2017-12-07T15:12:35+00:00",
"createdBy": "john.doe@bloomreach.com",
"modifiedAt": "2017-12-07T15:12:35+00:00",
"modifiedBy": "john.doe@bloomreach.com",
}
]
}
Upload distributionPOST/v3/distributions
Upload a distribution file. Add query parameter replace=true to replace an already uploaded distribution with the same name. This avoids appending a unique serial number to the file name.
Example URI
Headers
Authorization: Bearer [ authentication token ]
Content-type: [ multipart/form-data ]
Body
dist_file: [ file path location of the distribution file ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "4B36A01A8EBA74B7",
"distributionName": "dist_file",
"createdBy": "john.doe@bloomreach.com",
"createdAt": "2018-12-07T15:12:35+00:00",
"modifiedAt": "",
"modifiedBy": "",
"md5hash": "a9e1ad378cce8be60be89c1f7f1682a7"
}
400
Distribution InfoGET/v3/distributions/{id}
Retrieve distribution file information. The modifiedXx fields are updated when the file is renamed.
Example URI
- id
string
(required)Distribution file id
Headers
Authorization: Bearer [ authentication token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "E2E3927146F011A3",
"name": "cms-5.2-tar.gz",
"createdAt": "2017-12-07T15:12:35+00:00",
"createdBy": "john.doe@bloomreach.com",
"modifiedAt": "2017-15-07T15:13:45+00:00",
"modifiedBy": "marry.doe@bloomreach.com",
"md5hash": "a9e1ad378cce8be60be89c1f7f1682a7"
}
Rename distributionPATCH/v3/distributions/{id}
Rename a distribution file. The modifiedXx fields are updated when the file is renamed.
Example URI
- id
string
(required)Distribution file id
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
"name": "new_distribution_file_name.tgz"
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "E2E3927146F011A3",
"name": "new_distribution_file_name.tgz",
"createdAt": "2017-12-07T15:12:35+00:00",
"createdBy": "john@bloomreach.com",
"modifiedAt": "2017-12-07T15:12:35+00:00",
"modifiedBy": "marry@bloomreach.com",
"md5hash": "a9e1ad378cce8be60be89c1f7f1682a7"
}
Delete a distributionDELETE/v3/distributions/{id}
Delete a distribution file
Example URI
- id
string
(required)Distribution file id
Headers
Authorization: Bearer [ authentication token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
true
AppConfigFiles ¶
An appConfigFile can be used as a configuration file for a distribution per environment. Note that it is not possible to view or download an appConfigFile for security reasons. So it is recommended to store configuration files in a secrets manager and/or put them under version control depending on the sensitivity of the content. Use the md5 hash to check the uploaded file against the local file. Since a cms deploy is tight to a distribution and its appConfigFiles, their file names need to be unique. We recommend semantic versioning for the appConfigFile names to ensure uniqueness. See the deploy end point for more information.
App config files are not allowed to contain a key javax.net.truststore.
List appConfigFilesGET/v3/appconfigfiles
List appConfigFiles
Example URI
Headers
Authorization: Bearer [ authentication token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
[
{
"id": "4B36A01A8EBA74B7",
"name": "cms-4.1.0-appConfigFile.tar.gz",
"createdAt": "2017-12-07T15:12:35+00:00",
"createdBy": "john.doe@bloomreach.com",
"modifiedAt": "2017-12-07T15:12:35+00:00",
"modifiedBy": "john.doe@bloomreach.com",
"md5hash": "a9e1ad378cce8be60be89c1f7f1682a7"
}
]
}
400
Upload appConfigFilePOST/v3/appconfigfiles
Upload an appConfigFile file.
Example URI
Headers
Authorization: Bearer [ authentication token ]
Content-type: [ multipart/form-data ]
Body
appconfigfile: [ file path location of the appConfigFile ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "4B36A01A8EBA74B7",
"name": "license.properties",
"createdBy": "john.doe@bloomreach.com",
"createdAt": "2018-12-07T15:12:35+00:00",
"modifiedAt": "",
"modifiedBy": "",
"md5hash": "a9e1ad378cce8be60be89c1f7f1682a7"
}
400
AppConfigFile InfoGET/v3/appconfigfiles/{id}
Retrieve appConfigFile file information. The modifiedXx fields are updated when the file is renamed.
Example URI
- id
string
(required)appConfigFile id
Headers
Authorization: Bearer [ authentication token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "4B36A01A8EBA74B7",
"name": "license.properties",
"createdBy": "john.doe@bloomreach.com",
"createdAt": "2018-12-07T15:12:35+00:00",
"modifiedAt": "",
"modifiedBy": "",
"md5hash": "a9e1ad378cce8be60be89c1f7f1682a7"
}
Rename appConfigFilePATCH/v3/appconfigfiles/{id}
Rename an appConfigFile file. The modifiedXx fields are updated when the file is renamed.
Example URI
- id
string
(required)file id
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
"name": "newlicense.properties"
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "E2E3927146F011A3",
"name": "license.properties",
"createdAt": "2017-12-07T15:12:35+00:00",
"createdBy": "john@bloomreach.com",
"modifiedAt": "2017-12-07T15:12:35+00:00",
"modifiedBy": "marry@bloomreach.com",
"md5hash": "a9e1ad378cce8be60be89c1f7f1682a7"
}
Delete appConfigFileDELETE/v3/appconfigfiles/{id}
Delete appConfigFile file
Example URI
- id
string
(required)Distribution file id
Headers
Authorization: Bearer [ authentication token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
true
Domains ¶
Domains are used to direct incoming traffic with a host that matches the domain name to a specified environment.
List domainsGET/v3/domains
Example URI
Headers
Content-Type: application/json; charset=utf-8
Authorization: [ access token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
[
{
"id": "537980ce-beb3-467e-9f86-21a0cb4ee5a2",
"name": "example.onehippo.io",
"environmentId": "f69faf92-2ecd-4ade-a250-90172cb28d8c",
"createdAt": "2018-02-21T16:27:04+00:00",
"createdBy": "hippo-ondemand@bloomreach.com",
"updatedAt": "",
"updatedBy": ""
}
]
Get domainGET/v3/domains/{id}
Example URI
- id
string
(required)Domain id
Headers
Authorization: [ access token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "537980ce-beb3-467e-9f86-21a0cb4ee5a2",
"name": "example.onehippo.io",
"environmentId": "f69faf92-2ecd-4ade-a250-90172cb28d8c",
"createdAt": "2018-02-21T16:27:04+00:00",
"createdBy": "hippo-ondemand@bloomreach.com",
"updatedAt": "",
"updatedBy": ""
}
Get domain by nameGET/v3/domains/?name=domain_name
Example URI
Headers
Authorization: [ access token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "537980ce-beb3-467e-9f86-21a0cb4ee5a2",
"name": "example.onehippo.io",
"environmentId": "f69faf92-2ecd-4ade-a250-90172cb28d8c",
"createdAt": "2018-02-21T16:27:04+00:00",
"createdBy": "hippo-ondemand@bloomreach.com",
"updatedAt": "",
"updatedBy": ""
}
Add a new domainPOST/v3/domains
Add a new domain. This will direct incoming traffic with a host that matches the domain name to the specified environment.
The name field is required and must be unique to add a domain. The name must resememble a domain like for example customer.com
or www.customer.com and the name must match with one of the subject alternative names (SAN) in the customers SSL certificate.
This SSL certificate must be configured in the stack by the BRC team.
The environmentId is optional. This allows the domains to be specified upfront and used later on.
Source path and Target path is optional. You can specify route path ( source path ) and target path ( context path)
Example URI
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
"name": "customer.com",
"environmentId": "f69faf92-2ecd-4ade-a250-90172cb28d8c",
"sourcePath": "/",
"targetPath": "/marketing",
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "537980ce-beb3-467e-9f86-21a0cb4ee5a2",
"name": "example.onehippo.io",
"environmentId": "f69faf92-2ecd-4ade-a250-90172cb28d8c",
"createdAt": "2018-02-21T16:27:04+00:00",
"createdBy": "hippo-ondemand@bloomreach.com",
"updatedAt": "",
"updatedBy": "",
"sourcePath": "/",
"targetPath": "/marketing",
}
Update an existing domainPUT/v3/domains/{id}
Update the fields ‘name’ and ‘environmentId’ of an existing domain by passing in the domain id on the path. See the section Add a new domain on the requirements of the field name.
Example URI
- id
string
(required)Domain id
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
"name": "customer.com",
"environmentId": """,
"sourcePath": "/",
"targetPath": "/marketing",
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "537980ce-beb3-467e-9f86-21a0cb4ee5a2",
"name": "example.onehippo.io",
"environmentId": "",
"createdAt": "2018-02-21T16:27:04+00:00",
"createdBy": "hippo-ondemand@bloomreach.com",
"updatedAt": "2018-03-11T13:22:04+00:00",
"updatedBy": "hippo-ondemand@bloomreach.com"
"sourcePath": "/",
"targetPath": "/marketing",
}
Delete a domainDELETE/v3/domains/
Example URI
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
200
Body
{}
Environments ¶
An environment is the place where a cms deployment lives. An environment requires a distribution to be deployed, optionally together with configuration files (called AppConfigFiles). The required resources like a database and Elasticsearch are provided by the environment.
List environmentsGET/v3/environments
List all the environments
Example URI
Headers
Authorization: Bearer [ authentication token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"count": 4,
"items": [
{
"id": "F84A857BEBD63BEF",
"name": "samefile",
"url": "samefile-testing.onehippo.io",
"createdAt": "2017-12-07T15:12:35+00:00",
"createdBy": "john@bloomreach.com",
"deployedAt": "2017-12-07T15:14:42+00:00",
"deployedBy": "marry@bloomreach.com",
"distributionId": "81DF6E9CDCDA1813",
"state": "active",
"configuration": {
"bootstrap": false,
"virtualHosts": ["samefile-testing.onehippo.io"]
}
],
"max": -1,
"more": false,
"offset": 0,
"total": 4
}
Create EnvironmentPOST/v3/environments
Create a new environment
Example URI
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
"name": "new-environment-name"
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "91f28c69-cfb2-486d-9308-14d80",
"name": "mar06-qa01",
"url": "new-env-name-testing.onehippo.io",
"createdAt": "2017-12-07T15:12:35+00:00",
"createdBy": "hippo-ondemand@bloomreach.com",
"deployedAt": "",
"deployedBy": "",
"distributionId": "",
"state": "",
"configuration": {
"bootstrap": false,
"virtualHosts": [
"mar06-qa01-test.onehippo.io"
]
}
}
Deploy distributionPUT/v3/environments/{environmentId}/deploy
Deploy a distribution to an environment. This will start the CMS application within the distribution. During the deploy
the state field has the value ‘deploying’. When the deploy is finished, the state is ‘active’.
The deploy payload has an optional field called ‘strategy’. The default strategy is “stopstart”
If its value is “stopstart” then this means that BRC will first stop the environment and then deploy the distribution.
Especially when developing the project this is useful as the initialization is triggered by one container and the other
containers need to wait.
If its value is “rollingupdate” then the BRC will instead upgrade each pod individually without stopping the
environment. This means that there will not be any expected downtime, however this method can trigger
backwards-compatibility issues.
The deploy payload supports cms application configuration files (optional). The role of the file can be either ‘file’
which means it will be copied to the cms container as is or the role can be ‘systemproperty’. In the latter case
the file is treated as a Java system property file and its key value pairs will be passed on as Java system properties
to the Java runtime. If the role is ‘file’ then it is also possible to specify a new filename for the file to be copied
(optional). Since configuration file names need to be unique, this comes in very handy as the distribution can use
the same filename to read a configuration file.
Example URI
- environmentId
string
(required)Environment id
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
"distributionId": "F8A4CFAF8740B2C8",
"strategy" : "stopstart",
}
202
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "91f28c69-cfb2-486d-9308-14d803",
"name": "mar06-qa01",
"url": "new-env-name-testing.onehippo.io",
"createdAt": "2017-12-07T15:12:35+00:00",
"createdBy": "hippo-ondemand@bloomreach.com",
"deployedAt": "2019-07-29T12:09:50+00:00",
"deployedBy": "hippo-ondemand@bloomreach.com",
"distributionId": "cd04e191-95d8-a7d5-07c0370e9d6c",
"state": "deploying",
"configuration": {
"bootstrap": false,
"virtualHosts": [
"mar06-qa01-test.onehippo.io"
]
}
}
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
"distributionId": "F8A4CFAF8740B2C8",
"appConfigFileRoles": [
{
"appConfigFileId": "4bbb1f9c-733f-4709-9ec3-3b7d3a40507c",
"role": "file",
"newFilename": "db.properties"
},
{
"appConfigFileId": "533b4426-acb1-42dc-b062-d0e2f09d3f6e",
"role": "systemproperty"
}
]
}
202
Headers
Content-Type: application/json; charset=utf-8
Body
""
Get environmentGET/v3/environments/{environmentId}
Get environment information
Example URI
- environmentId
string
(required)Environment id
Headers
Authorization: Bearer [ authentication token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "8CA48B97CD9369F3",
"name": "mar06-qa02",
"url": "mar06-qa02-testing.onehippo.io",
"createdAt": "2017-12-07T15:12:35+00:00",
"createdBy": "joe@bloomreach.com",
"deployedAt": "2017-12-07T15:14:42+00:00",
"deployedBy": "wendy@bloomreach.com",
"distributionId": "F8A4CFAF8740B2C8",
"state": "active",
"configuration": {
"bootstrap": false,
"virtualHosts": [
"mar06-qa02-testing.onehippo.io"
]
}
}
Get environment by nameGET/v3/environments?name={name}
Get environment information by passing in environment name as query parameter. Note that using the environment’s id in scripts is safer since environment names are not guaranteed to be unique in time.
Example URI
- name
string
(required)name of the environment
Headers
Authorization: Bearer [ authentication token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "8CA48B97CD9369F3",
"name": "mar06-qa02",
"url": "mar06-qa02-testing.onehippo.io",
"createdAt": "2017-12-07T15:12:35+00:00",
"createdBy": "joe@bloomreach.com",
"deployedAt": "2017-12-07T15:14:42+00:00",
"deployedBy": "wendy@bloomreach.com",
"distributionId": "F8A4CFAF8740B2C8",
"state": "active",
"configuration": {
"bootstrap": false,
"virtualHosts": [
"mar06-qa02-testing.onehippo.io"
]
}
}
Generate "Download token"POST/v3/environments/:environmentId/logs/download-token
Generate download token for environment’s CMS logs (cms, site, catalina, etc).
Example URI
Headers
Authorization: Bearer [ authentication token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"token": "0cef47e192e0786eeb3e4d082dc2653247fd0f97adebd0b985ed0a4b0c44350f"
}
401
Download Environment CMS logsGET/v3/environments/logs/download/:download_log_token
Download CMS logs of an environment (cms, site, catalina, etc) using the download token.
Example URI
Headers
Authorization: Bearer [ authentication token ]
200
Headers
Content-Type: application/json; charset=utf-8
accept-ranges: →bytes
content-disposition: →attachment; filename="cmslogs feb01qa01 2018-02-09 0910.tar.gz"
content-length: →13442
404
Body
{
"error_code": "InvalidDownloadToken",
"error_detail": "Download token '3b42c66d8b07a389dsafa1968ad8d7f25c1659b0a' not valid."
}
Delete an environmentDELETE/v3/environments/{environmentId}
Delete an existing environment
Example URI
- environmentId
string
(required)Environment id
Headers
Authorization: Bearer [ authentication token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
null
Mark an environment as production environment (DEPRECATED)PUT/v3/production/
This endpoint is deprecated. Please use /v3/production2.
An environment marked as production gets more resources from Bloomreach Cloud to handle more load.
You can mark an environment as a production environment by calling this api endpoint and passing in the old production
environment id (optional) and the new environment id. It is also possible
to make all domain rules point from the old to the new environment by setting the body field ‘changeDomainRules’ to true.
The max number of production environments is by default 1. In case you want to change this contact Bloomreach.
In case you exceed the max number of production environments a 404 with error MaxProdEnvsReached is returned.
In case an environment is not a production environment (anymore), you can set ‘newProductionEnvironmentId’ to empty.
Example URI
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
"currentProductionEnvironmentId": "8414f067-ba9e-9306-7c5c5cb3992f",
"newProductionEnvironmentId": "45414f067-bc9e-1402-3c5cfab3432f",
"changeDomainRules": "true"
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
null
Mark an environment as a production environmentPUT/v3/production2/
An environment marked as production gets more resources from Bloomreach Cloud to handle more load.
You can mark an environment as a production environment by passing in the environment id.
If there is an existing production environment, it is possible to point domain rules from the existing production environment to the new production environment by setting the body field ‘changeDomainRules’ to true.
Only one environment can be marked as production. By setting a new environment as a production, the environment that used to be production will get scaled down and unmarked as production.
Passing the emtpy ‘newProductionEnvironmentId’ will unmark current production environment as such.
This API call is asynchronous, it scedules all the needed operations and returns a job token that has to be polled via the /v3/jobs endpoint.
Example URI
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
"newProductionEnvironmentId": "45414f067-bc9e-1402-3c5cfab3432f",
"changeDomainRules": "true"
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"JobID": "94029e739-ea88-1402-3c5cfab3444"
}
Poll job statusGET/v3/jobs/{jobID}
This endpoint is BETA, it’s semantics and/or path might change without notice.
Returns the status of an asynchronous job.
Status of a job can be either “started” or “done”. If job is “done”, the success is determined by the “Err” field.
If “Err” is empty, the job completed successfully, otherwise it will contain a description of a problem.
Example URI
- jobID
string
(required)ID of a job
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
null
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"Err": "",
"Status": "started"
}
Protect the site and/or cms of an environmentPUT/v3/environments/{environmentId}/protect/
By enabling protection of the site and/or cms, the visitor needs to enter the environment name as username and the password as specified in the rest call. Protecting the site can be handy in case you do not want to expose the site to the public (yet). Protecting the CMS can be handy in case of maintenance. Only users with the password can access the CMS or the console. These users still need to login into the CMS or console as in normal conditions.
Example URI
- environmentId
string
(required)Environment id
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
"site": true,
"sitepassword": "I love you",
"cms": false,
"cmspassword": "I love you more"
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
null
Mark deployment as failedPUT/v3/environments/{environmentId}/markasfailed/
When the CMS and/or site do not start up properly, you can mark the environment as failed. Make sure the CMS is not still indexing or busy with other intensive operations. To do so, consult the logs. After marking an environment as failed, you can (re)deploy or restore backup. It is adviced to restore a backup since the repository can be in an undetermined state.
Example URI
- environmentId
string
(required)Environment id
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
null
Heap dump ¶
API that allows you to create and download a heap dump, also the heap dump automatically created by the JVM in case of OOME. Note that there can be at most one manual and one automated created heap dump. So to get a newly automated created heap dump, you need to delete the existing one. Only admin role can make dumps for production environment.
Create heap dumpPOST/v3/environments/{environmentId}/heapdump
Use the Location header to download the dump file.
Example URI
- environmentId
string
(required)Environment id
Headers
Authorization: Bearer [ authentication token ]
202
Headers
Content-Type: application/json; charset=utf-8
Download heap dump created by APIGET/v3/environments/{environmentId}/heapdump/apicreated
By specifying the Accept-Encoding: gzip header, BRC will compress the dump. This will substantially reduce the size of the download.
Example URI
- environmentId
string
(required)Environment id
Headers
Authorization: Bearer [ authentication token ]
Accept-Encoding: gzip
Body
{}
200
Headers
Content-Type: application/json; charset=utf-8
List heap dumps created through API and/or by JVM in case of out of memory exceptionGET/v3/environments/{environmentId}/heapdump
By specifying the Accept-Encoding: gzip header, BRC will compress the dump. This will substantially reduce the size of the download.
Example URI
- environmentId
string
(required)Environment id
Headers
Authorization: Bearer [ authentication token ]
Accept-Encoding: gzip
Body
{}
200
Headers
Content-Type: application/json; charset=utf-8
Download created heap dump by JVM when out of memory exception occursGET/v3/environments/{environmentId}/heapdump/oomcreated
You need to delete the heap dump after download so a new heap dump can be created by the jvm when an oom occurs.
Example URI
- environmentId
string
(required)Environment id
Headers
Authorization: Bearer [ authentication token ]
Accept-Encoding: gzip
Body
{}
200
Headers
Content-Type: application/json; charset=utf-8
Delete an automatically created heap dumpDELETE/v3/environments/{environmentId}/heapdump/oomcreated
You can do the same for the manually created heap dumps by replacing /oomcreated with /apicreated in the path.
Example URI
- environmentId
string
(required)Environment id
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
200
Thread dump ¶
API that allows you to create and download thread dumps
Create thread dumpPOST/v3/environments/{environmentId}/threaddump
Example URI
- environmentId
string
(required)Environment id
Headers
Authorization: Bearer [ authentication token ]
202
Headers
Content-Type: application/json; charset=utf-8
Download thread dump created through APIGET/v3/environments/threaddump/apicreated
By specifying the Accept-Encoding: gzip header, BRC will compress the dump. This will substantially reduce the size of the download.
Example URI
Headers
Authorization: Bearer [ authentication token ]
Accept-Encoding: gzip
Body
{}
200
Headers
Content-Type: application/json; charset=utf-8
List thread dump created by APIGET/v3/environments/threaddump
By specifying the Accept-Encoding: gzip header, BRC will compress the dump. This will substantially reduce the size of the download.
Example URI
Headers
Authorization: Bearer [ authentication token ]
Accept-Encoding: gzip
Body
{}
200
Headers
Content-Type: application/json; charset=utf-8
Custom Error Pages ¶
API that sets custom error pages for specfic eror codes.
Set customErrorPagePOST/v3/customerrorpages/{errorcode}
Currently only http status / error code 503 is supported. In case you want to remove an existing custom error page, you can set ‘fileId’ to empty.
Example URI
- errorcode
string
(required)http status code, currently only 503 supported
Headers
Authorization: Bearer [ authentication token ]
Body
{
"fileId": [app config file id]
}
200
Headers
Content-Type: application/json; charset=utf-8
Backup and Restore ¶
API that drives backup and restore process across the BRC platform
List all backupsGET/v3/backups
Example URI
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
[
{
"id": "01b23258-eb79-41f0-8c3b-ad2a7d29b566",
"environmentId": "cafebabe-1234",
"createdBy": "user@bloomreach.com",
"createdAt": "2017-12-07T15:12:35+00:00",
"distributionId": "3791ED1FD651C039",
"databases": [
{
"id": "011280fc-55da-4b52-8483-df7ef0164acd",
"database": "green",
"filePath": "/backups/environments/green/databases/green/abc123_green.gz"
},
{
"id": "9807340d-d8b7-4477-96da-9ccf76c93d33",
"database": "green_targeting",
"filePath": "/backups/environments/green_/databases/green__targeting/92f4p5b9mr_green_targeting.gz"
}
],
"backupType": "Manual"
},
{
"id": "f3412a37-2d65-4499-bdf9-5ec979ced6a9",
"environmentId": "cafebabe-5678",
"createdBy": "user@bloomreach.com",
"createdAt": "2017-12-07T15:12:35+00:00",
"distributionId": "",
"databases": [
{
"id": "cdc004c2-8d06-4761-b67d-cbc9042ea04f",
"database": "blue",
"filePath": "/backups/environments/jan17qa01/databases/jan17qa01/j37o43hmi3_blue.gz"
},
{
"id": "703123af-a265-4c96-b1e6-67393eb84e6e",
"database": "blue_targeting",
"filePath": "/backups/environments/blue/databases/blue_targeting/mookjrcnl1_blue_targeting.gz"
}
],
"backupType": "Manual"
},
{
"id": "7dbabb2c-d4b6-4ca6-b5db-fe07bd6b4a36",
"createdBy": "user@bloomreach.com",
"createdAt": "2017-12-07T15:12:35+00:00",
"backupType": "SharedDatastoreBackup"
}
]
Get download link for repostitory database of backupGET/v3/backups/{backupId}/repositorydownloadlink
Get a link to AWS S3 to download the repository database of the backup. The downloaded archive contains a MySQL dump of the repository. The link to s3 is valid for 15 minutes.
Example URI
- backupId
string
(required)The id of backup that contains the repository to download
Headers
Authorization: Bearer [ authentication token ]
200
Body
{
"url":"https://backups-cust-onehippo-io.s3.eu-west-1.amazonaws.com/backups/environments/421f-....-1d6808/databases/421fd41f-4417-41d6-8be8-1719668d6808/ce9f76....6808.gz?X-Amz-Algorithm=AWS4-HMAC-SHA256\u0026X-Amz-Credential=AKIAZ..._request\u0026X-Amz-Date=20200527T110427Z\u0026X-Amz-Expires=604800\u0026X-Amz-SignedHeaders=host\u0026X-Amz-Signature=9ccc....c"}
}
401
Headers
Content-Type: application/json; charset=utf-8
Body
{
"error_code": "ObjectNotFound",
"error_uid": "54877c97-3fa1-4ea1-ae58-8bca1fe6c3e9",
"error_detail": "Backup with id 'eb3b02f7-48b3-4298-82d23232543d51' is not found"
}
Create backup of environment's databasesPOST/v3/backups
Example URI
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
"environmentId": [environment id],
"backupType": Manual
}
202
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "f3e3b02a-f5b4-4357-8255-da1e4685e6c3",
"environmentId": [environment id],
"createdBy": "user@bloomreach.com",
"createdAt": "2017-12-07T15:12:35+00:00",
}
400
Headers
Content-Type: application/json; charset=utf-8
Body
{
"error_code": "InvalidParameters",
"error_detail": "Empty environmentId"
}
Create backup of shared datastore tablePOST/v3/backups/shareddatastore
Shared-datastore means that all blobs across environments are stored in the same database table. Reach out to Bloomreach Support to enable this feature. Backup records of this type cannot be restored, they are exclusively for download purposes (see repositorydownloadlink). Backups of shared datastore might take considerable amount of time to be created (hours). In order to check the status of the backup record created by this API endpoint, please supply the returned id to the /v3/backups/jobs/ API endpoint.
Example URI
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
202
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "f3e3b02a-f5b4-4357-8255-da1e4685e6c3",
"environmentId": "",
"createdBy": "user@bloomreach.com",
"createdAt": "2017-12-07T15:12:35+00:00",
"type": "SharedDatastoreBackup"
}
Restore a backupPUT/v3/backups/{backupId}/restore
Only backup records of type ‘Manual’ or ‘StackSnapshot’ can be restored. Backup records of type ‘SharedDatastoreBackup’ cannot be restored, they are exclusivery for download purposes (see repositorydownloadlink).
Example URI
- backupId
string
(required)The id of backup to restore
Headers
Authorization: Bearer [ authentication token ]
Body
{
"environmentId": [target environment id]
}
202
Body
Response contains the restoring job id.
{
"jobId": "f3e3b02a-f5b4-4357-1234-da1e46855678"
}
400
Headers
Content-Type: application/json; charset=utf-8
Body
{
"error_code": "InvalidParameters",
"error_detail": [detail message]
}
Monitor a running jobGET/v3/backups/jobs/{jobId}
Example URI
- jobId
string
(required)The id in the responses of the creating backup call or the restoring backup call
Headers
Authorization: Bearer [ authentication token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"jobId": [monitored jobId],
"status": "completed"
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"jobId": [monitored jobId],
"status": "running"
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"jobId": [monitored jobId],
"status": "error"
}
Delete backupDELETE/v3/backups/{backupId}
Delete forever the manually created backup from the repository. System created backups cannot be deleted.
Example URI
- backupId
string
(required)The id of backup to delete
Headers
Authorization: Bearer [ authentication token ]
200
400
Headers
Content-Type: application/json; charset=utf-8
Body
{
"error_code": "InvalidParameters",
"error_detail": [detail message]
}
Users ¶
Listing usersGET/v3/users
Example URI
Headers
Content-Type: application/json; charset=utf-8
Authorization: [ access token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
[
{
"id": "bca4bc54-61c7-42ca-b6a5-0b04bd1823ec",
"username": "user1@bloomreach.com",
"role": "root",
"active": true
},
{
"id": "15d4d7c1-a48f-4567-b139-96c36e9ecbbe",
"username": "user2@bloomreach.com",
"role": "admin",
"active": true
}
]
400
Headers
Content-Type: application/json; charset=utf-8
Body
{
"error_code": "RetrieveUsersFailed",
"error_detail": [detail message]
}
Get user detailGET/v3/users/{username}
Example URI
- username
string
(required)Username to query
Headers
Authorization: [ access token ]
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "15d4d7c1-a48f-4567-b139-96c36e9ecbbe",
"username": "exampleuser@bloomreach.com",
"role": "user",
"active": true,
}
400
Headers
Content-Type: application/json; charset=utf-8
Body
{
"error_code": "RetrieveUsersFailed",
"error_detail": [detail message]
}
Add a new userPOST/v3/users
Add a new user. Username, password, role (user, admin or root) and active fields are required to add an user. The username must be a valid email address. The password must be at least 8 characters long and contain digit, lower and upper case characters.
Example URI
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
"username": "exampleuser@bloomreach.com",
"password": [super secret password],
"role": "user",
"active": "true",
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "15d4d7c1-a48f-4567-b139-96c36e9ecbbe",
"username": "exampleuser@bloomreach.com",
"role": "user",
"active": true
}
400
Update an existing userPUT/v3/users/{username}
Update the fields ‘active’ and ‘role’ of an existing user by passing in the username on the path. Username cannot be changed. Admin or root role required to update an user
Example URI
- username
string
(required)Name of the user to update
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
"active" : false
"role": "user"
}
200
Headers
Content-Type: application/json; charset=utf-8
Body
{
"id": "15d4d7c1-a48f-4567-b139-96c36e9ecbbe",
"username": "exampleuser@bloomreach.com",
"role": "user",
"active": true
}
400
Change user passwordPUT/v3/users/{username}/password
Change or update passwords
Example URI
- username
string
(required)The username to change password
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
Body
{
"currentPassword": "P4ssw0rd123",
"newPassword": "N3wExamplePassword123"
}
200
401
Headers
Content-Type: application/json; charset=utf-8
Body
{
"error_code": "ChangePasswordFailed",
"error_detail": [detail message]
}
Send reset-password emailPOST/v3/password-reset/{username}
Request reset-password token
Example URI
- username
string
(required)The username to send reset-password email
Headers
Content-Type: application/json; charset=utf-8
200
400
Verify reset-password tokenGET/v3/password-reset/{token}
Verify the reset-password token and redirect to the change password page
Example URI
- token
string
(required)The reset-password token sent by email.
Headers
Content-Type: application/json; charset=utf-8
302
Headers
Location: [URL of the change password webpage]
400
Set new passwordPUT/v3/password-reset/password
Set the new password to the user referred by the reset token
Example URI
Headers
Content-Type: application/json; charset=utf-8
Body
{
"reset_token": [ generated reset-token ],
"new_password": [new password]
}
200
400
Delete a userDELETE/v3/users/{username}
Example URI
- username
string
(required)Name of the user to be deleted
Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer [ authentication token ]
200
400
Headers
Content-Type: application/json; charset=utf-8
Body
{
"error_code": "RemoveUserFailed",
"error_detail": [detail message]
}