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

ParameterTypeRequiredDescription
releaseIdURLYesPath parameter for the release Id

Response

Release JSON objects can having the following attributes:

AttributeTypeDescription

releaseId

LongThe id of the release
releaseNameStringThe name of the release
releaseStatusString

The current status of the release. Possible statuses are NOTSTARTED, STARTED,

SUSPENDED, and COMPLETED

descriptionStringThe description of the release
pipelineIdLongThe id of the pipeline used by the release
pipelineNameStringThe name of the pipeline used by the release
startDateStringThe date the release started
endDateStringThe date the release ended
scheduleBuildExpressionStringThe CRON expression which is used to schedule builds. Multiple CRON expressions can be specified and must be separated by a semicolon
projectsList<ReleaseProjects>The list of projects associated with the release. See more about ReleaseProjects below.
propertiesList<PropertyValue>The list of properties associated with the configured pipeline. See more about the PropertyValue below.

Elements of ReleaseProjects have the following attributes:

AttributeTypeDescription
priorityIntegerThe priority of the project
projectIdLongThe id of the project
packageNameStringThe package name for the project (partial deployment projects only)
requestAllFilesBoolean

Whether or not the project includes all files (partial deployment projects only)

buildEnvironmentIdLongThe id of the build environment for the project
projectStreamIdLongThe id of the Stream which the project/package was built from
projectGroupsStringGroups the project is in, based on groups defined in associated pipeline

Elements of PropertyValue have the following attributes:

AttributeTypeDescription
propertyNameStringName of the property
propertyValueStringValue of the property

Response Codes

HTTP CodeDescription
200Release was found and returned
401Authentication failure
403Authorization failure (no access to resource)
404Release not found
500Unexpected 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

ParameterTypeRequiredDescription
releaseNameString (Query)NoQuery based on the name of the release. Name is case insensitive. The service will query for release names which contain the release name provided.
releaseStatusString (Query)NoQuery 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:

AttributeTypeDescription

releaseId

LongThe id of the release
releaseNameStringThe name of the release
releaseStatusString

The current status of the release. Possible statuses are NOTSTARTED, STARTED,

SUSPENDED, and COMPLETED

descriptionStringThe description of the release
pipelineIdLongThe id of the pipeline used by the release
pipelineNameStringThe name of the pipeline used by the release
startDateStringThe date the release started
endDateStringThe date the release ended
scheduleBuildExpressionStringThe expression which is used to schedule builds
projectsList<ReleaseProjects>The list of projects associated with the release. See more about ReleaseProjects below.
propertiesList<PropertyValue>The list of properties associated with the configured pipeline. See more about the PropertyValue below.

Elements of ReleaseProjects have the following attributes:

AttributeTypeDescription
priorityIntegerThe priority of the project
projectIdLongThe id of the project
packageNameStringThe package name for the project (partial deployment projects only)
requestAllFilesBoolean

Whether or not the project includes all files (partial deployment projects only)

buildEnvironmentIdLongThe id of the build environment for the project
projectStreamIdLongThe id of the Stream which the project/package was built from
projectGroupsStringGroups the project is in, based on groups defined in associated pipeline

Elements of PropertyValue have the following attributes:

AttributeTypeDescription
propertyNameStringName of the property
propertyValueStringValue of the property

Response Codes

HTTP CodeDescription
200Search successful and results returned
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
500Unexpected 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:

AttributeTypeRequiredDescription
releaseNameStringYesThe name of the release
releaseStatusStringNo

The current status of the release. Possible statuses for the request are NOTSTARTED and STARTED. Default status is NOTSTARTED

descriptionStringNoThe description of the release
pipelineIdLongNoThe id of the pipeline used by the release
pipelineNameStringNoThe name of the pipeline used by the release
scheduleBuildExpressionStringNoThe expression which is used to schedule builds
projectsList<ReleaseProjects>NoThe list of projects associated with the release. See more about ReleaseProjects below.
propertiesList<PropertyValue>NoThe list of properties associated with the configured pipeline. See more about the PropertyValue below.

Elements of ReleaseProjects have the following attributes:

AttributeTypeDescription
priorityIntegerThe priority of the project
projectIdLongThe id of the project
packageNameStringThe package name for the project (partial deployment projects only)
requestAllFilesBoolean

Whether or not the project includes all files (partial deployment projects only)

buildEnvironmentIdLongThe id of the build environment for the project
projectStreamIdLongThe id of the Stream which the project/package was built from
projectGroupsStringGroups the project is in, based on groups defined in associated pipeline

Elements of PropertyValue have the following attributes:

AttributeTypeDescription
propertyNameStringName of the property
propertyValueStringValue of the property

Response

Release JSON objects can have the following attributes:

AttributeTypeDescription

releaseId

LongThe id of the release
releaseNameStringThe name of the release
releaseStatusString

The current status of the release. Possible statuses are NOTSTARTED, STARTED,

SUSPENDED, and COMPLETED

descriptionStringThe description of the release
pipelineIdLongThe id of the pipeline used by the release
pipelineNameStringThe name of the pipeline used by the release
startDateStringThe date the release started
endDateStringThe date the release ended
scheduleBuildExpressionStringThe expression which is used to schedule builds
projectsList<ReleaseProjects>

The list of projects associated with the release. See more about ReleaseProjects below.

propertiesList<PropertyValue>The list of properties associated with the configured pipeline. See more about the PropertyValue below.

Elements of ReleaseProjects have the following attributes:

AttributeTypeDescription
priorityIntegerThe priority of the project
projectIdLongThe id of the project
packageNameStringThe package name for the project (partial deployment projects only)
requestAllFilesBoolean

Whether or not the project includes all files (partial deployment projects only)

buildEnvironmentIdLongThe id of the build environment for the project
projectStreamIdLongThe id of the Stream which the project/package was built from
projectGroupsStringGroups the project is in, based on groups defined in associated pipeline

Elements of PropertyValue have the following attributes:

AttributeTypeDescription
propertyNameStringName of the property
propertyValueStringValue of the property

Response Codes

HTTP CodeDescription
201Release created
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
500Unexpected 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.

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:

AttributeTypeRequiredDescription
releaseNameStringYesThe name of the release
releaseStatusStringNo

The current status of the release. Possible statuses for the request are NOTSTARTED and STARTED. Default status is NOTSTARTED

descriptionStringNoThe description of the release
pipelineIdLongNoThe id of the pipeline used by the release
pipelineNameStringNoThe name of the pipeline used by the release
scheduleBuildExpressionStringNoThe expression which is used to schedule builds
projectsList<ReleaseProjects>NoThe list of projects associated with the release. See more about ReleaseProjects below.
propertiesList<PropertyValue>NoThe list of properties associated with the configured pipeline. See more about the PropertyValue below.

Elements of ReleaseProjects have the following attributes:

AttributeTypeDescription
priorityIntegerThe priority of the project
projectIdLongThe id of the project
packageNameStringThe package name for the project (partial deployment projects only)
requestAllFilesBoolean

Whether or not the project includes all files (partial deployment projects only)

buildEnvironmentIdLongThe id of the build environment for the project
projectStreamIdLongThe id of the Stream which the project/package was built from
projectGroupsStringGroups the project is in, based on groups defined in associated pipeline

Elements of PropertyValue have the following attributes:

AttributeTypeDescription
propertyNameStringName of the property
propertyValueStringValue of the property

Response

Release JSON objects can have the following attributes:

AttributeTypeDescription

releaseId

LongThe id of the release
releaseNameStringThe name of the release
releaseStatusString

The current status of the release. Possible statuses are NOTSTARTED, STARTED,

SUSPENDED, and COMPLETED

descriptionStringThe description of the release
pipelineIdLongThe id of the pipeline used by the release
pipelineNameStringThe name of the pipeline used by the release
startDateStringThe date the release started
endDateStringThe date the release ended
scheduleBuildExpressionStringThe expression which is used to schedule builds
projectsList<ReleaseProjects>

The list of projects associated with the release. See more about ReleaseProjects below.

propertiesList<PropertyValue>The list of properties associated with the configured pipeline. See more about the PropertyValue below.

Elements of ReleaseProjects have the following attributes:

AttributeTypeDescription
priorityIntegerThe priority of the project
projectIdLongThe id of the project
packageNameStringThe package name for the project (partial deployment projects only)
requestAllFilesBoolean

Whether or not the project includes all files (partial deployment projects only)

buildEnvironmentIdLongThe id of the build environment for the project
projectStreamIdLongThe id of the Stream which the project/package was built from
projectGroupsStringGroups the project is in, based on groups defined in associated pipeline

Elements of PropertyValue have the following attributes:

AttributeTypeDescription
propertyNameStringName of the property
propertyValueStringValue of the property

Response Codes

HTTP CodeDescription
200Release updated
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
500Unexpected 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.

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:

AttributeTypeRequiredDescription
releaseNameStringNoThe name of the release
releaseStatusStringNo

The desired status of the release. Possible statuses are NOTSTARTED, STARTED,

SUSPENDED, and COMPLETED

descriptionStringNoThe description of the release
pipelineIdLongNoThe id of the pipeline used by the release
pipelineNameStringNoThe name of the pipeline used by the release
scheduleBuildExpressionStringNoThe expression which is used to schedule builds
projectsList<ReleaseProjects>NoThe list of projects associated with the release. See more about ReleaseProjects below.
propertiesList<PropertyValue>NoThe list of properties associated with the configured pipeline. See more about the PropertyValue below.

Elements of ReleaseProjects have the following attributes:

AttributeTypeDescription
priorityIntegerThe priority of the project
projectIdLongThe id of the project
packageNameStringThe package name for the project (partial deployment projects only)
requestAllFilesBoolean

Whether or not the project includes all files (partial deployment projects only)

buildEnvironmentIdLongThe id of the build environment for the project
projectStreamIdLongThe id of the Stream which the project/package was built from
projectGroupsStringGroups the project is in, based on groups defined in associated pipeline

Elements of PropertyValue have the following attributes:

AttributeTypeDescription
propertyNameStringName of the property
propertyValueStringValue of the property

Response

Release JSON objects can have the following attributes:

AttributeTypeDescription

releaseId

LongThe id of the release
releaseNameStringThe name of the release
releaseStatusString

The current status of the release. Possible statuses are NOTSTARTED, STARTED,

SUSPENDED, and COMPLETED

descriptionStringThe description of the release
pipelineIdLongThe id of the pipeline used by the release
pipelineNameStringThe name of the pipeline used by the release
startDateStringThe date the release started
endDateStringThe date the release ended
scheduleBuildExpressionStringThe expression which is used to schedule builds
projectsList<ReleaseProjects>

The list of projects associated with the release. See more about ReleaseProjects below.

propertiesList<PropertyValue>The list of properties associated with the configured pipeline. See more about the PropertyValue below.

Elements of ReleaseProjects have the following attributes:

AttributeTypeDescription
priorityIntegerThe priority of the project
projectIdLongThe id of the project
packageNameStringThe package name for the project (partial deployment projects only)
requestAllFilesBoolean

Whether or not the project includes all files (partial deployment projects only)

buildEnvironmentIdLongThe id of the build environment for the project
projectStreamIdLongThe id of the Stream which the project/package was built from
projectGroupsStringGroups the project is in, based on groups defined in associated pipeline

Elements of PropertyValue have the following attributes:

AttributeTypeDescription
propertyNameStringName of the property
propertyValueStringValue of the property

Response Codes

HTTP CodeDescription
200Release updated
400Bad request
401Authentication failure
403Authorization failure (no access to resource)
500Unexpected 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"
       }     
   ]
}