Release API
Releases can be retrieved through this API using a GET service.
Authentication - Use Basic Authentication for this API.
GET
There are two implementations of GET. One will find a Release with the given Id and return the JSON representation of the Release. The other will find a list of Releases matching the parameters supplied to it.
GET (By Id)
This GET service will return the JSON representation of a release given a release Id.
Request
Parameter | Type | Required | Description |
---|---|---|---|
releaseId | URL | Yes | Path parameter for the release Id |
Response
Release JSON objects can having the following attributes:
Attribute | Type | Description |
---|---|---|
releaseId | Long | The id of the release |
releaseName | String | The name of the release |
releaseStatus | String | The current status of the release. Possibles statuses are NOTSTARTED, STARTED, SUSPENDED, and COMPLETED |
description | String | The description of the release |
pipelineId | Long | The id of the pipeline used by the release |
pipelineName | String | The name of the pipeline used by the release |
startDate | String | The date the release started |
endDate | String | The date the release ended |
scheduleBuildExpression | String | The CRON expression which is used to schedule builds |
projects | List<ReleaseProjects> | The list of projects associated with the release. See more about ReleaseProjects below. |
cmsDetails | ReleaseCMSDetails | The details for a Change Management System in release. See more about the ReleaseCMSDetails below. |
properties | List<PropertyValue> | The list of properties associated with the configured pipeline. See more about the PropertyValue below. |
Elements of ReleaseProjects have the following attributes:
Attribute | Type | Description |
---|---|---|
priority | Integer | The priority of the project |
projectId | Long | The id of the project |
packageName | String | The package name for the project (partial deployment projects only) |
requestAllFiles | Boolean | Whether or not the project includes all files (partial deployment projects only) |
buildEnvironmentId | Long | The id of the build environment for the project |
projectStreamId | Long | The id of the Stream which the project/package was built from |
projectGroups | String | Groups the project is in, based on groups defined in associated pipeline |
Elements of PropertyValue have the following attributes:
Attribute | Type | Description |
---|---|---|
propertyName | String | Name of the property |
propertyValue | String | Value of the property |
Elements of ReleaseCMSDetails have the following attributes:
Attribute | Type | Description |
---|---|---|
cmsInstanceId | Long | The instance id for the Change Management System |
overrideSettings | Boolean | Whether or not the settings for the Change Management System should be overridden in this release |
overriddenDefaultConfigurations | ReleaseCMSOverrideDefaultConfig | Information about the default overridden configuration for the Change Management System. See more about the ReleaseCMSOverrideDefaultConfig below. |
overriddenEnvironmentConfigurations | List<ReleaseCMSOverrideEnvConfig> | Information about the overridden environment configurations for the Change Management System. See more about the ReleaseCMSOverrideEnvConfig below. |
Elements of ReleaseCMSOverrideDefaultConfig have the following attributes:
Attribute | Type | Description |
---|---|---|
requireChangeTicketForDeployment | Boolean | Allows override of whether a change ticket is required for deployment by default for the Change Management System |
Elements of ReleaseCMSOverrideEnvConfig have the following attributes:
Attribute | Type | Description |
---|---|---|
environmentId | Long | Id of the environment to override settings |
requireChangeTicketForDeployment | Boolean | Whether a change ticket is required for deploying to this environment |
Response Codes
HTTP Code | Description |
---|---|
200 | Release was found and returned |
401 | Authentication failure |
403 | Authorization failure (no access to resource) |
404 | Release not found |
500 | Unexpected internal server error |
Example
If a release in our database had an id of 14321 and a GET request was sent to http://host:port/flexdeploy/rest/v1/releases/14321
A release JSON object will be returned with the following release information:
{ "releaseId": 14321, "releaseName": "Test Release 1", "description": "", "pipelineId": 10004, "pipelineName": "Simple Pipeline", "startDate": "2019-02-13", "endDate": null, "scheduleBuildExpression": null, "releaseStatus": "STARTED", "projects": [ { "priority": 1, "projectId": 10000, "packageName": "package1", "projectName": "REST Project 1", "requestAllFiles": false, "applicationPath": "FlexDeploy/REST", "buildEnvironmentId": 21212, "projectStreamId": 13900, "projectGroups": null }, { "priority": 2, "projectId": 10001, "packageName": null, "projectName": "REST Project 2", "requestAllFiles": false, "applicationPath": "FlexDeploy/REST", "buildEnvironmentId": 10056, "projectStreamId": 15986, "projectGroups": null }] }
GET (Using Query Parameters)
This GET service will return the JSON representation of a list of releases given release query parameters.
API URL
http://host:port/flexdeploy/rest/v1/releases
Request
Parameter | Type | Required | Description |
---|---|---|---|
releaseName | String (Query) | No | Query based on the name of the release. Name is case insensitive. The service will query for release names which contain the release name provided. |
releaseStatus | String (Query) | No | Query based on the status of the release. Possible statuses are NOT STARTED, STARTED, SUSPENDED, and COMPLETED. Status is case insensitive. |
If no query parameters are provided, all releases will be returned.
Response
Release JSON objects can have the following attributes:
Attribute | Type | Description |
---|---|---|
releaseId | Long | The id of the release |
releaseName | String | The name of the release |
releaseStatus | String | The current status of the release. Possibles statuses are NOTSTARTED, STARTED, SUSPENDED, and COMPLETED |
description | String | The description of the release |
pipelineId | Long | The id of the pipeline used by the release |
pipelineName | String | The name of the pipeline used by the release |
startDate | String | The date the release started |
endDate | String | The date the release ended |
scheduleBuildExpression | String | The expression which is used to schedule builds |
projects | List<ReleaseProjects> | The list of projects associated with the release. See more about ReleaseProjects below. |
cmsDetails | ReleaseCMSDetails | The details for a Change Management System in release. See more about the ReleaseCMSDetails below. |
properties | List<PropertyValue> | The list of properties associated with the configured pipeline. See more about the PropertyValue below. |
Elements of ReleaseProjects have the following attributes:
Attribute | Type | Description |
---|---|---|
priority | Integer | The priority of the project |
projectId | Long | The id of the project |
packageName | String | The package name for the project (partial deployment projects only) |
requestAllFiles | Boolean | Whether or not the project includes all files (partial deployment projects only) |
buildEnvironmentId | Long | The id of the build environment for the project |
projectStreamId | Long | The id of the Stream which the project/package was built from |
projectGroups | String | Groups the project is in, based on groups defined in associated pipeline |
Elements of PropertyValue have the following attributes:
Attribute | Type | Description |
---|---|---|
propertyName | String | Name of the property |
propertyValue | String | Value of the property |
Elements of ReleaseCMSDetails have the following attributes:
Attribute | Type | Description |
---|---|---|
cmsInstanceId | Long | The instance id for the Change Management System |
overrideSettings | Boolean | Whether or not the settings for the Change Management System should be overridden in this release |
overriddenDefaultConfigurations | ReleaseCMSOverrideDefaultConfig | Information about the default overridden configuration for the Change Management System. See more about the ReleaseCMSOverrideDefaultConfig below. |
overriddenEnvironmentConfigurations | List<ReleaseCMSOverrideEnvConfig> | Information about the overridden environment configurations for the Change Management System. See more about the ReleaseCMSOverrideEnvConfig below. |
Elements of ReleaseCMSOverrideDefaultConfig have the following attributes:
Attribute | Type | Description |
---|---|---|
requireChangeTicketForDeployment | Boolean | Allows override of whether a change ticket is required for deployment by default for the Change Management System |
Elements of ReleaseCMSOverrideEnvConfig have the following attributes:
Attribute | Type | Description |
---|---|---|
environmentId | Long | Id of the environment to override settings |
requireChangeTicketForDeployment | Boolean | Whether a change ticket is required for deploying to this environment |
Response Codes
HTTP Code | Description |
---|---|
200 | Search successful and results returned |
400 | Bad request |
401 | Authentication failure |
403 | Authorization failure (no access to resource) |
500 | Unexpected internal server error |
Example
If we want to see all releases with a name containing 'Rest' with a status of STARTED, we would send this request:
Request: http://host:port/flexdeploy/rest/v1/releases?releaseStatus=STARTED&releaseName=Rest
A GET request would be triggered and return the following JSON release objects:
[ { "description": null, "endDate": null, "startDate": "2019-02-05", "projects": [ { "priority": 1, "packageName": null, "projectGroups": null, "projectName": "RESTDeployProject1", "projectId": 13903, "requestAllFiles": false, "projectStreamId": 13904, "buildEnvironmentId": 10956, "applicationPath": "FlexDeploy/RESTTests" }, { "priority": 1, "packageName": "Package2", "projectGroups": null, "projectName": "RESTDeployPartialProject", "projectId": 13921, "requestAllFiles": false, "projectStreamId": 13922, "buildEnvironmentId": 10956, "applicationPath": "FlexDeploy/RESTTests" }, { "priority": 1, "packageName": "Package1", "projectGroups": null, "projectName": "RESTDeployPartialProject", "projectId": 13921, "requestAllFiles": false, "projectStreamId": 13922, "buildEnvironmentId": 10956, "applicationPath": "FlexDeploy/RESTTests" } ], "pipelineId": 10004, "scheduleBuildExpression": null, "releaseStatus": "STARTED", "releaseId": 12101, "releaseName": "REST Release 1", "pipelineName": "Test Pipeline" }, { "description": null, "endDate": null, "startDate": "2019-02-05", "projects": [ { "priority": 1, "packageName": null, "projectGroups": null, "projectName": "RESTDeployPartialProject", "projectId": 13921, "requestAllFiles": true, "projectStreamId": 13922, "buildEnvironmentId": 10956, "applicationPath": "FlexDeploy/RESTTests" }, { "priority": 1, "packageName": null, "projectGroups": null, "projectName": "RESTDeployProject1", "projectId": 13903, "requestAllFiles": false, "projectStreamId": 13904, "buildEnvironmentId": 10956, "applicationPath": "FlexDeploy/RESTTests" } ], "pipelineId": 10004, "scheduleBuildExpression": null, "releaseStatus": "STARTED", "releaseId": 12104, "releaseName": "REST Release 2", "pipelineName": "Test Pipeline" } ]
POST (create release)
This POST service will create a new release with the same attributes as the given JSON object.
API URL
http://host:port/flexdeploy/rest/v1/releases
Request
POST will receive a release input JSON object and return a release JSON object. Release input JSON objects for the request can have the following attributes:
Attribute | Type | Required | Description |
---|---|---|---|
releaseName | String | Yes | The name of the release |
releaseStatus | String | No | The current status of the release. Possibles statuses for the request are NOTSTARTED and STARTED. Default status is NOTSTARTED |
description | String | No | The description of the release |
pipelineId | Long | No | The id of the pipeline used by the release |
pipelineName | String | No | The name of the pipeline used by the release |
scheduleBuildExpression | String | No | The expression which is used to schedule builds |
projects | List<ReleaseProjects> | No | The list of projects associated with the release. See more about ReleaseProjects below. |
cmsDetails | ReleaseCMSDetails | No | The details for a Change Management System in release. See more about the ReleaseCMSDetails below. |
properties | List<PropertyValue> | No | The list of properties associated with the configured pipeline. See more about the PropertyValue below. |
Elements of ReleaseProjects have the following attributes:
Attribute | Type | Description |
---|---|---|
priority | Integer | The priority of the project |
projectId | Long | The id of the project |
packageName | String | The package name for the project (partial deployment projects only) |
requestAllFiles | Boolean | Whether or not the project includes all files (partial deployment projects only) |
buildEnvironmentId | Long | The id of the build environment for the project |
projectStreamId | Long | The id of the Stream which the project/package was built from |
projectGroups | String | Groups the project is in, based on groups defined in associated pipeline |
Elements ofPropertyValue have the following attributes:
Attribute | Type | Description |
---|---|---|
propertyName | String | Name of the property |
propertyValue | String | Value of the property |
Elements of ReleaseCMSDetails have the following attributes:
Attribute | Type | Description |
---|---|---|
cmsInstanceId | Long | The instance id for the Change Management System |
overrideSettings | Boolean | Whether or not the settings for the Change Management System should be overridden in this release |
overriddenDefaultConfigurations | ReleaseCMSOverrideDefaultConfig | Information about the default overridden configuration for the Change Management System. See more about the ReleaseCMSOverrideDefaultConfig below. |
overriddenEnvironmentConfigurations | List<ReleaseCMSOverrideEnvConfig> | Information about the overridden environment configurations for the Change Management System. See more about the ReleaseCMSOverrideEnvConfig below. |
Elements of ReleaseCMSOverrideDefaultConfig have the following attributes:
Attribute | Type | Description |
---|---|---|
requireChangeTicketForDeployment | Boolean | Allows override of whether a change ticket is required for deployment by default for the Change Management System |
Elements of ReleaseCMSOverrideEnvConfig have the following attributes:
Attribute | Type | Description |
---|---|---|
environmentId | Long | Id of the environment to override settings |
requireChangeTicketForDeployment | Boolean | Whether a change ticket is required for deploying to this environment |
Response
Release JSON objects can have the following attributes:
Attribute | Type | Description |
---|---|---|
releaseId | Long | The id of the release |
releaseName | String | The name of the release |
releaseStatus | String | The current status of the release. Possibles statuses are NOTSTARTED, STARTED, SUSPENDED, and COMPLETED |
description | String | The description of the release |
pipelineId | Long | The id of the pipeline used by the release |
pipelineName | String | The name of the pipeline used by the release |
startDate | String | The date the release started |
endDate | String | The date the release ended |
scheduleBuildExpression | String | The expression which is used to schedule builds |
projects | List<ReleaseProjects> | The list of projects associated with the release. See more about ReleaseProjects below. |
cmsDetails | ReleaseCMSDetails | The details for a Change Management System in release. See more about the ReleaseCMSDetails below. |
properties | List<PropertyValue> | The list of properties associated with the configured pipeline. See more about the PropertyValue below. |
Elements of ReleaseProjects have the following attributes:
Attribute | Type | Description |
---|---|---|
priority | Integer | The priority of the project |
projectId | Long | The id of the project |
packageName | String | The package name for the project (partial deployment projects only) |
requestAllFiles | Boolean | Whether or not the project includes all files (partial deployment projects only) |
buildEnvironmentId | Long | The id of the build environment for the project |
projectStreamId | Long | The id of the Stream which the project/package was built from |
projectGroups | String | Groups the project is in, based on groups defined in associated pipeline |
Elements of PropertyValue have the following attributes:
Attribute | Type | Description |
---|---|---|
propertyName | String | Name of the property |
propertyValue | String | Value of the property |
Elements of ReleaseCMSDetails have the following attributes:
Attribute | Type | Description |
---|---|---|
cmsInstanceId | Long | The instance id for the Change Management System |
overrideSettings | Boolean | Whether or not the settings for the Change Management System should be overridden in this release |
overriddenDefaultConfigurations | ReleaseCMSOverrideDefaultConfig | Information about the default overridden configuration for the Change Management System. See more about the ReleaseCMSOverrideDefaultConfig below. |
overriddenEnvironmentConfigurations | List<ReleaseCMSOverrideEnvConfig> | Information about the overridden environment configurations for the Change Management System. See more about the ReleaseCMSOverrideEnvConfig below. |
Elements of ReleaseCMSOverrideDefaultConfig have the following attributes:
Attribute | Type | Description |
---|---|---|
requireChangeTicketForDeployment | Boolean | Allows override of whether a change ticket is required for deployment by default for the Change Management System |
Elements of ReleaseCMSOverrideEnvConfig have the following attributes:
Attribute | Type | Description |
---|---|---|
environmentId | Long | Id of the environment to override settings |
requireChangeTicketForDeployment | Boolean | Whether a change ticket is required for deploying to this environment |
Response Codes
HTTP Code | Description |
---|---|
201 | Release created |
400 | Bad request |
401 | Authentication failure |
403 | Authorization failure (no access to resource) |
500 | Unexpected internal server error |
Example
If the POST request sent to http://host:port/flexdeploy/rest/v1/releases receives the following JSON release object,
{ "releaseName":"Release Created From REST API", "releaseStatus": "STARTED", "pipelineId":12345, "properties": [ { "propertyName": "TESTPROPERTY", "propertyValue": 3 }], "projects":[ { "projectId": 33442, "packageName": "Package 1" }], "cmsDetails": { "cmsInstanceId": 01010 } }
The following release object will then be created in FlexDeploy:
{ "projects": [ { "buildEnvironmentId": null, "projectGroups": null, "packageName": "Package 1", "projectId": 33442, "projectStreamId": 3502, "requestAllFiles": false, "priority": 1 }], "startDate": null, "endDate": null, "scheduleBuildExpression": null, "pipelineId": 12345, "releaseStatus": "STARTED", "cmsDetails": { "cmsInstanceId": 01010, "overriddenDefaultConfigurations": null, "overriddenEnvironmentConfigurations": null, "overrideSettings": false }, "description": null, "releaseName": "Release Created From REST API", "releaseId": 13607, "pipelineName": "Pipeline 1", "properties": [ { "propertyValue": "3", "propertyName": "TESTPROPERTY" } ] }
PUT (update release)
This PUT service will update all attributes of a release with the given Id based on the attributes of a JSON object parameters. If an attribute is null it will delete or reset those attributes to their default value.
Minimum Requirements
ReleaseId and ReleaseName are required for PUT
Notes
- Cannot start a release without at least one project (Full deployment or partial deployment).
- Cannot add a project without all required property values for that property set.
- Cannot end a release if there are running pipeline executions.
- If PipelineName and PipelineID is provided, both must point to the same Pipeline.
- PipelineName or PipelineId must be provided to set Pipeline Properties.
- Adding a project requires a Project ID and Project Stream ID.
- When adding a new project to the release, if no buildEnvironmentId is passed, then the service will attempt to initialize the BuildEnvironmentId if only one build environment instance is associated to it.
- BuildEnvironmentId must be a build environment and associated with the project's build instance under Topology
- Full Deployment Projects:
- Cannot provide packageName or requestAllFiles
- Partial Deployment Projects:
- Cannot provide packageName if requestAllFiles is true
- Must provide packageName if requestAllFile is false
- Examples of valid Cron Expressions
Request
PUT will receive a release input JSON object and return a release JSON object. Release input JSON objects for the request can have the following attributes:
Attribute | Type | Required | Description |
---|---|---|---|
releaseName | String | Yes | The name of the release |
releaseStatus | String | No | The current status of the release. Possibles statuses for the request are NOTSTARTED and STARTED. Default status is NOTSTARTED |
description | String | No | The description of the release |
pipelineId | Long | No | The id of the pipeline used by the release |
pipelineName | String | No | The name of the pipeline used by the release |
scheduleBuildExpression | String | No | The expression which is used to schedule builds |
projects | List<ReleaseProjects> | No | The list of projects associated with the release. See more about ReleaseProjects below. |
cmsDetails | ReleaseCMSDetails | No | The details for a Change Management System in release. See more about the ReleaseCMSDetails below. |
properties | List<PropertyValue> | No | The list of properties associated with the configured pipeline. See more about the PropertyValue below. |
Elements of ReleaseProjects have the following attributes:
Attribute | Type | Description |
---|---|---|
priority | Integer | The priority of the project |
projectId | Long | The id of the project |
packageName | String | The package name for the project (partial deployment projects only) |
requestAllFiles | Boolean | Whether or not the project includes all files (partial deployment projects only) |
buildEnvironmentId | Long | The id of the build environment for the project |
projectStreamId | Long | The id of the Stream which the project/package was built from |
projectGroups | String | Groups the project is in, based on groups defined in associated pipeline |
Elements of PropertyValue have the following attributes:
Attribute | Type | Description |
---|---|---|
propertyName | String | Name of the property |
propertyValue | String | Value of the property |
Elements of ReleaseCMSDetails have the following attributes:
Attribute | Type | Description |
---|---|---|
cmsInstanceId | Long | The instance id for the Change Management System |
overrideSettings | Boolean | Whether or not the settings for the Change Management System should be overridden in this release |
overriddenDefaultConfigurations | ReleaseCMSOverrideDefaultConfig | Information about the default overridden configuration for the Change Management System. See more about the ReleaseCMSOverrideDefaultConfig below. |
overriddenEnvironmentConfigurations | List<ReleaseCMSOverrideEnvConfig> | Information about the overridden environment configurations for the Change Management System. See more about the ReleaseCMSOverrideEnvConfig below. |
Elements of ReleaseCMSOverrideDefaultConfig have the following attributes:
Attribute | Type | Description |
---|---|---|
requireChangeTicketForDeployment | Boolean | Allows override of whether a change ticket is required for deployment by default for the Change Management System |
Elements of ReleaseCMSOverrideEnvConfig have the following attributes:
Attribute | Type | Description |
---|---|---|
environmentId | Long | Id of the environment to override settings |
requireChangeTicketForDeployment | Boolean | Whether a change ticket is required for deploying to this environment |
Response
Release JSON objects can have the following attributes:
Attribute | Type | Description |
---|---|---|
releaseId | Long | The id of the release |
releaseName | String | The name of the release |
releaseStatus | String | The current status of the release. Possibles statuses are NOTSTARTED, STARTED, SUSPENDED, and COMPLETED |
description | String | The description of the release |
pipelineId | Long | The id of the pipeline used by the release |
pipelineName | String | The name of the pipeline used by the release |
startDate | String | The date the release started |
endDate | String | The date the release ended |
scheduleBuildExpression | String | The expression which is used to schedule builds |
projects | List<ReleaseProjects> | The list of projects associated with the release. See more about ReleaseProjects below. |
cmsDetails | ReleaseCMSDetails | The details for a Change Management System in release. See more about the ReleaseCMSDetails below. |
properties | List<PropertyValue> |