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.

API URL

http://host:port/flexdeploy/rest/v1/releases/{releaseId}

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

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:

Response JSON

{
	"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.
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

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:

GET JSON Response

[
      {
      "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.
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

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

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,

POST JSON

{
	"releaseName":"Release Created From REST API",
	"releaseStatus": "STARTED",
	"pipelineId":12345,
	"properties": [
	{
		"propertyName": "TESTPROPERTY",
		"propertyValue": 3
	}],
	"projects":[
	{
		"projectId": 33442,
		"packageName": "Package 1"
	}]
}

The following release object will then be created in FlexDeploy:

POST JSON

{
   "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",,
   "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.

API URL

http://host:port/flexdeploy/rest/v1/releases/{releaseId}

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

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

Response Codes

HTTP Code	Description
200	Release updated
400	Bad request
401	Authentication failure
403	Authorization failure (no access to resource)
500	Unexpected internal server error

Example

If we had a release in our database with an Id of 11101 and had the following attributes

Release PUT JSON

{
   "projects": [   {
      "buildEnvironmentId": null,
      "projectGroups": null,
      "packageName": "Package 1",
      "projectId": 33442,
      "projectStreamId": 3502,
      "requestAllFiles": false,
      "priority": 1
   }],
   "startDate": null,
   "endDate": null,
   "scheduleBuildExpression": null,
   "pipelineId": null
   "releaseStatus": "STARTED",
   "description": null,
   "releaseName": "Release Created From REST API",
   "releaseId": 13607,
   "pipelineName": null,
   "properties": []
}

When we run a PUT request at the following URL

http://host:port/flexdeploy/rest/v1/releases/11101

And the PUT request receives the following JSON release object,

Release PUT Receive JSON

{
   "projects": [
		"projectId": 6789,
		"projectStreamId": 6790
	],
   "startDate": null,
   "endDate": null,
   "scheduleBuildExpression": null,
   "pipelineId": 12345,
   "releaseStatus": "NOTSTARTED",
   "description": "This is the updated Release",
   "releaseName": "Release Created From REST API",
   "pipelineName": "Pipeline 1",
   "properties":    [
       {
         "propertyValue": "3",
         "propertyName": "TESTPROPERTY"
       }     
   ]
}

The PUT request would then update the release with Id 11101 and return the following JSON release object. Notice that project with Id 33442 was removed and project with Id 6789 was added to the release. In this case, the buildEnvironmentId was automatically initialized.

Release PUT Return JSON

{
   "projects": [
      "buildEnvironmentId": 22478,
      "projectGroups": null,
      "packageName": null,
      "projectId": 6789,
      "projectStreamId": 6790,
      "requestAllFiles": false,
      "priority": 1
	],
   "startDate": null,
   "endDate": null,
   "scheduleBuildExpression": null,
   "pipelineId": 12345,
   "releaseStatus": "STARTED",
   "description": "This is the updated Release",
   "releaseName": "Release Created From REST API",
   "releaseId": 13607,
   "pipelineName": "Pipeline 1",
   "properties":    [
       {
         "propertyValue": "3",
         "propertyName": "TESTPROPERTY"
       }     
   ]
}

PATCH (append new or update existing)

This PATCH service will update an existing release with the information passed through a JSON object. PATCH will only add new data or update existing data, and does not support removing data.

API URL

http://host:port/flexdeploy/rest/v1/releases/{releaseId}

Minimum Requirements

ReleaseId and ReleaseName are required for PATCH

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

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

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

Response Codes

HTTP Code	Description
200	Release updated
400	Bad request
401	Authentication failure
403	Authorization failure (no access to resource)
500	Unexpected internal server error

Example

If we had a release in our database with an Id of 11101 and had the following attributes

Release PATCH JSON

{
   "projects": []
   "startDate": null,
   "endDate": null,
   "scheduleBuildExpression": null,
   "pipelineId": null
   "releaseStatus": "STARTED",
   "description": null,
   "releaseName": "Release Created From REST API",
   "releaseId": 13607,
   "pipelineName": null,
   "properties": []
}

When we run a PATCH request at the following URL

http://host:port/flexdeploy/rest/v1/releases/11101

And the PATCH request receives the following JSON release object.

Release PATCH Receive JSON

{
   "projects": [   {
      "projectId": 33442,
      "projectStreamId": 3502
   }],
   "pipelineId": 12345,
   "releaseStatus": "NOTSTARTED",
   "releaseName": "Release Created From REST API",
   "pipelineName": "Pipeline 1",
   "properties":    [
       {
         "propertyValue": "3",
         "propertyName": "TESTPROPERTY"
       }     
   ]
}

The PATCH request would then update the release with Id 11101 and return the following JSON release object.

Release PATCH Return JSON

{
   "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",
   "description": "This is the updated Release",
   "releaseName": "Release Created From REST API",
   "releaseId": 13607,
   "pipelineName": "Pipeline 1",
   "properties":    [
       {
         "propertyValue": "3",
         "propertyName": "TESTPROPERTY"
       }     
   ]
}