Snapshots can be created through this API using a POST service and snapshot information can be retrieved using a GET service.

Table of Contents

maxLevel	1

...

GET

GET (By Id)

This POST GET service will create return the JSON representation of a new snapshot with the same attributes as the given JSON objectgiven a snapshot Id.

Info

title	API URL

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

...

Request

POST will receive a snapshot input JSON object and return a snapshot JSON object. Snapshot input JSON objects can have the following attributes:

Parameter	Type	Required	Description

...

snapshotId

URL

Yes

Path parameter for the

...

should be set to createSnapshot for this API.

...

A list of project versions to be built or existing versions to be associated with new snapshot.
If you do not provide projectVersionId, build will be initiated.
If you do not supply specific project that is configured in release, it will be added for build. projectId and packageName is used to identify if project is configured in Release or not.
If you supply projectId and packageName combination that is not part of release, exception will be thrown.
If you do not provide anything for this attribute, build will be initiated for all project in Release.

Elements of snapshotVersionInputs has following attributes:

...

Yes for partial deploy,

otherwise No

...

Response

Snapshot JSON objects can having the following attributes:

...

snapshotId

...

The status of the snapshot. Possible values are:

COMPLETED - The snapshot was successfully assembled, but has not yet been sent to pipeline for execution.
FAILED - The snapshot failed to be assembled (which could mean the underlying build failed).
FAILED TO INITIATE - The snapshot was assembled, but failed to be sent to the pipeline for execution.
INITIATED - The snapshot has been sent to the pipeline for execution.
PENDING - The snapshot is in the process of being assembled and set to the pipeline for execution.

...

Elements of snapshotVersions has following attributes:

...

The current status of the individual project version within the snapshot. Possible values are:

PENDING - The project is has not yet been built for the snapshot.
SUBMITTED - The project is currently being built for the snapshot.
COMPLETED - The project has been built successfully for the snapshot.
FAILED - The project has failed to build.
EXISTING - The snapshot is utilizing an already built version of the project.

Response Codes

...

Example

If the POST request sent to http://host:port/flexdeploy/rest/v1/releases/12345/snapshot receives the following JSON environment object,

...

theme	Eclipse
title	POST JSON

...

snapshot Id which is used to return a snapshot
releaseId	URL	Yes	Path parameter for the release Id which contains the snapshot that will be returned

Response

Snapshot JSON objects can having the following attributes:

Attribute	Type	Description
snapshotId	Long	The id of the snapshot
snapshotName	String	The name of the snapshot, which is generated based on the time of creation
snapshotStatus	String	The status of the snapshot. Possible values are: COMPLETED - The snapshot was successfully assembled, but has not yet been sent to pipeline for execution. FAILED - The snapshot failed to be assembled (which could mean the underlying build failed). FAILED TO INITIATE - The snapshot was assembled, but failed to be sent to the pipeline for execution. INITIATED - The snapshot has been sent to the pipeline for execution. PENDING - The snapshot is in the process of being assembled and sent to the pipeline for execution.
description	String	The description of the snapshot
snapshotVersions	List<SnapshotVersionPojo>	The version information about the projects/packages contained within this snapshot

Elements of snapshotVersions has following attributes:

Attribute	Type	Description
projectId	Long	The id of the project
projectStreamId	Long	The id of the Stream which the project/package was built from
projectVersionId	Long	The version id of the project
packageName	String	The name of the package (partial deployment projects only)
requestAllFiles	Boolean	Whether or not the project includes all files (partial deployment projects only)
snapshotVersionStatus	String	The current status of the individual project version within the snapshot. Possible values are: PENDING - The project is has not yet been built for the snapshot. SUBMITTED - The project is currently being built for the snapshot. COMPLETED - The project has been built successfully for the snapshot. FAILED - The project has failed to build. EXISTING - The snapshot is utilizing an already built version of the project.

Response Codes

HTTP Code	Description
200	Snapshot was found and returned
400	Bad request
401	Authentication failure
403	Authorization failure (no access to resource)
404	Release or snapshot not found
500	Unexpected internal server error

Example

If a snapshot in our database had an id of 10005 and releaseId of 14321 and a GET request was sent to http://host:port/flexdeploy/rest/v1/releases/14321/snapshot/10005

A Snapshot JSON object will be returned with snapshot information:

Code Block

theme	Eclipse
title	Response JSON

{
	"snapshotId": 10005,
	"snapshotName": "07-09-2018 12:15:03",
	"description": "",
	"snapshotStatus": "INITIATED",
	"snapshotVersions": [
	{
		"projectId": 10000,
		"packageName": "package1",
		"projectVersionId": 10025,
		"requestAllFiles": false,
		"snapshotVersionStatus": "EXISTING"
	},
	{
		"projectId": 10000,
		"packageName": "package2",
		"projectVersionId": 10040,
		"requestAllFiles": false,
		"snapshotVersionStatus": "EXISTING"
	},
	{
		"projectId":

...

10002,
		"packageName": null,
		"

...

projectVersionId"

...

10065,

...

requestAllFiles":

...

false,
		"

...

snapshotVersionStatus":

...

"EXISTING"
	}

...

]
}

...

The following snapshot object will then be created in FlexDeploy:

Code Block

theme	Eclipse
title	POST JSON

{
	"snapshotId": 10005,
	"snapshotName": "07-09-2018 12:12:03",
	"description": "example snapshot creation",
	"snapshotStatus": "PENDING",
	"snapshotVersions": [
	{
		"projectId": 10000,
		"packageName": "package1",
		"projectVersionId": 10001,
		"requestAllFiles": false,
		"snapshotVersionStatus": "EXISTING"
	},
	{
		"projectId": 10000,
		"packageName": "package2",
		"projectVersionId": null,
		"requestAllFiles": false,
		"snapshotVersionStatus": "PENDING"
	},
	{
		"projectId": 10002,
		"packageName": null,
		"projectVersionId": null,
		"requestAllFiles": false,
		"snapshotVersionStatus": "PENDING"
	}]
}

POST (promote to release)

Project versions can be promoted to a release through this POST service. Promoting a project to release will combine the specified version of the specified project with the versions of the other projects used in the last snapshot into a new snapshot.

Info

title	URL for promoting a project version to a release

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

Request

POST will receive a snapshot input JSON object and return a snapshot JSON object. Snapshot input JSON objects can have the following attributes:

...

Elements of snapshotVersionInputs has following attributes:

...

Response

Snapshot JSON objects can having the following attributes:

...

snapshotId

...

The status of the snapshot. Possible values are:

COMPLETED - The snapshot was successfully assembled, but has not yet been sent to pipeline for execution.
FAILED - The snapshot failed to be assembled (which could mean the underlying build failed).
FAILED TO INITIATE - The snapshot was assembled, but failed to be sent to the pipeline for execution.
INITIATED - The snapshot has been sent to the pipeline for execution.
PENDING - The snapshot is in the process of being assembled and set to the pipeline for execution.

...

Elements of snapshotVersions has following attributes:

...

The current status of the individual project version within the snapshot. Possible values are:

PENDING - The project is has not yet been built for the snapshot.
SUBMITTED - The project is currently being built for the snapshot.
COMPLETED - The project has been built successfully for the snapshot.
FAILED - The project has failed to build.
EXISTING - The snapshot is utilizing an already built version of the project.

Response Codes

...

Example

If the previous snapshot had the following attributes:

...

theme	Eclipse
title	Current JSON

...

GET (Using Query Parameters)

This GET service will return the JSON representation of a list of snapshots given the release id and snapshot query parameters. Results are sorted so latest snapshots are returned first.

Info

title	API URL

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

Request

Parameter	Type	Required	Description
releaseId	Long (URL)	Yes	Path parameter for the release Id. All returned snapshots will be in this release.
snapshotName	String (Query)	No	Query based on the generated name of the snapshot. Name is case sensitive and must be exact.
snapshotStatus	String (Query)	No	Query based on the status of the snapshot. Possible statuses are COMPLETED, FAILED, FAILED TO INITIATE, INITIATED, and PENDING. Status is case insensitive.
limit	Integer (Query)	No	Limits the number of snapshots returned to specified value. If no limit is provided, all snapshots matching the criteria are returned.

Tip
If no query parameters are provided, all the snapshots in the release will be returned.

Response

Snapshot JSON objects can have the following attributes:

Attribute	Type	Description
snapshotId	Long	The id of the snapshot
snapshotName	String	The name of the snapshot, which is generated based on the time of creation
snapshotStatus	String	The status of the snapshot. Possible values are: COMPLETED - The snapshot was successfully assembled, but has not yet been sent to pipeline for execution. FAILED - The snapshot failed to be assembled (which could mean the underlying build failed). FAILED TO INITIATE - The snapshot was assembled, but failed to be sent to the pipeline for execution. INITIATED - The snapshot has been sent to the pipeline for execution. PENDING - The snapshot is in the process of being assembled and sent to the pipeline for execution.
description	String	The description of the snapshot
snapshotVersions	List<SnapshotVersionPojo>	The version information about the projects/packages contained within this snapshot

Elements of snapshotVersions has the following attributes:

Attribute	Type	Description
projectId	Long	The id of the project
projectStreamId	Long	The id of the Stream which the project/package was built from
projectVersionId	Long	The version id of the project
packageName	String	The name of the package (partial deployment projects only)
requestAllFiles	Boolean	Whether or not the project includes all files (partial deployment projects only)
snapshotVersionStatus	String	The current status of the individual project version within the snapshot. Possible values are: PENDING - The project is has not yet been built for the snapshot. SUBMITTED - The project is currently being built for the snapshot. COMPLETED - The project has been built successfully for the snapshot. FAILED - The project has failed to build. EXISTING - The snapshot is utilizing an already built version of the project.

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 have a release with id 11211 and want to see the latest 2 snapshots with a status of COMPLETED, we would send this request:

Request: http://host:port/flexdeploy/rest/v1/releases/11211/snapshot?status=COMPLETED&limit=2

A GET request would be triggered and return the following JSON snapshots object:

Code Block

theme	Eclipse
title	GET JSON Response

[
	{
		"snapshotId": 11501,
		"snapshotStatus": "COMPLETED",
		"snapshotVersions": [
		{
			"snapshotVersionStatus": "COMPLETED",
			"projectVersionId": 33129,
			"projectId": 25208,
			"packageName": null,
			"projectStreamId": 25209,
			"requestAllFiles": false
		},
		{
			"snapshotVersionStatus": "COMPLETED",
			"projectVersionId": 33175,
			"projectId": 25228,
			"packageName": "Package1",
			"projectStreamId": 25229,
			"requestAllFiles": false
		},
		{
			"snapshotVersionStatus": "COMPLETED",
			"projectVersionId": 33146,
			"projectId": 25228,
			"packageName": "Package2",
			"projectStreamId": 25229,
			"requestAllFiles": false
		}
		],
		"snapshotName": "02-08-2019 08:52:02",
		"description": null
	},
	{
		"

...

snapshotId":

...

11346,
		"

...

snapshotStatus":

...

"COMPLETED",
		"

...

snapshotVersions":

...

[
		{
			"snapshotVersionStatus": "COMPLETED",
			"projectVersionId": 32466,
			"projectId": 25208,
			"packageName": null,
			"projectStreamId": 25209,
			"requestAllFiles": false
		},
		{
			"snapshotVersionStatus": "COMPLETED",

...

And a POST request was sent to http://host:port/flexdeploy/rest/v1/releases/{releaseId}/snapshot with the following JSON object input:

Code Block

theme	Eclipse
title	POST JSON

{
	"action" : "promoteToRelease",
    "description": "example snapshot creation",
	"snapshotVersionInputs": [
	{
		"projectId": 10000,
		"packageName": "package1",
		"projectVersionId": 10025
	} ]
}

The following Snapshot JSON object will begin:

Code Block

theme	Eclipse
title	Response JSON

{
	"snapshotId": 10025,
	"snapshotName": "07-09-2018 12:15:03",
	"description": "",
	"snapshotStatus": "INITIATED",
	"snapshotVersions": [
	{
		"projectId": 10000,
		"packageName": "package1",
		"projectVersionId": 10025,
		"requestAllFiles": false,
		"snapshotVersionStatus": "EXISTING"
	},
	{
		"projectId": 10000,
		"packageName": "package2",
		"projectVersionId": 10040,
		"requestAllFiles": false,
		"snapshotVersionStatus": "EXISTING"
	},
	{
		"projectId": 10002,
		"packageName": null,
		"projectVersionId": 10065,
		"requestAllFiles": false,
		"snapshotVersionStatus": "EXISTING"
	}]
}

GET (By Id)

This GET service will return the JSON representation of a snapshot given a snapshot Id.

Info

title	API URL

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

Request

ParameterTypeRequiredDescriptionsnapshotIdURLYesPath parameter for the snapshot Id which is used to return a snapshotreleaseIdURLYesPath parameter for the release Id which contains the snapshot that will be returned

			"projectVersionId": 32436,
			"projectId": 25228,
			"packageName": null,
			"projectStreamId": 25229,
			"requestAllFiles": true
		}
		],
	"snapshotName": "02-06-2019 16:35:04",
	"description": null
	}
]

POST (create snapshot)

This POST service will create a new snapshot with the same attributes as the given JSON object.

Info

title	API URL

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

Request

POST will receive a snapshot input JSON object and return a snapshot JSON object. Snapshot input JSON objects can have the following attributes:

Attributes	Type	Required	Description
releaseId	URL	Yes	Path parameter for the release Id where the snapshot will be added
action	String	Yes	should be set to createSnapshot for this API.
description	String	No	The description of the snapshot
snapshotVersionInputs	List<SnapshotVersionInputPojo>	No	A list of project versions to be built or existing versions to be associated with new snapshot. If you do not provide projectVersionId, build will be initiated. If you do not supply specific project that is configured in release, it will be added for build. projectId and packageName is used to identify if project is configured in Release or not. If you supply projectId and packageName combination that is not part of release, exception will be thrown. If you do not provide anything for this attribute, build will be initiated for all project in Release.

Elements of snapshotVersionInputs has following attributes:

Attributes	Type	Required	Description
projectId	Long	Yes	Project associated with release.
projectVersionId	Long	No	The version id of the project. If project version is not supplied new build will be performed.
packageName	String	Yes for partial deploy, otherwise No	The name of the package (used for partial deployment projects only) associated with release. If Partial deployment project and packageName is not supplied it will be considered all files type version.
buildEnvironmentId	Long	No	The build environment associated with the project. If not supplied and only one environment found for build instance then it will be defaulted.
forceBuild	Boolean	No	Whether or not the project should be force built. This will be overridden to true for partial deployment project.

Response

Snapshot JSON objects can having the following attributes:

...

Attributes	Type	Description
snapshotId	Long	The id of the snapshot
snapshotName	String	The name of the snapshot,

...

which is

...

the time

...

when the snapshot was created

snapshotStatus

String

The status of the snapshot. Possible values are:

COMPLETED - The snapshot was successfully assembled, but has not yet been sent to pipeline for execution.
FAILED - The snapshot failed to be assembled (which could mean the underlying build failed).
FAILED TO INITIATE - The snapshot was assembled, but failed to be sent to the pipeline for execution.
INITIATED - The snapshot has been sent to the pipeline for execution.
PENDING - The snapshot is in the process of being assembled and

...

set to the pipeline for execution.
description	String	The description of the snapshot
snapshotVersions	List<SnapshotVersionPojo>	The version information about the projects

...

associated with the snapshot

Elements of snapshotVersions has following attributes:

...

Attributes	Type	Description
projectId	Long	The id of the project
projectStreamId	Long	The id of the Stream which the project/package was built from.
projectVersionId	Long	The version id of the project
packageName	String	The name of the package (used for partial deployment projects only)
requestAllFiles	Boolean	Whether or not the project

...

was told to request all files

...

snapshotVersionStatus

String

The current status of the individual project version within the snapshot. Possible values are:

PENDING - The project is has not yet been built for the snapshot.
SUBMITTED - The project is currently being built for the snapshot.
COMPLETED - The project has been built successfully for the snapshot.
FAILED - The project has failed to build.
EXISTING - The snapshot is utilizing an already built version of the project.

Response Codes

HTTP Code	Description

...

201

Snapshot

...

created
401	Authentication failure
403	Authorization failure (no access to resource)
404	Release

...

not found
500	Unexpected internal server error

Example

If

...

the POST request sent to http://host:port/flexdeploy/rest/v1/releases/12345/snapshot receives the following JSON environment object,

Code Block

theme	Eclipse
title	POST JSON

{
	"action" : "createSnapshot",
    "description": "example snapshot creation",
	"snapshotVersionInputs": [
	{
		"projectId": 10000,
		"packageName": "package1",
		"projectVersionId": 10001
	},
	{
		"projectId": 10000,
		"packageName": "package2",
	},
	{
		"projectId": 10002,
		"buildEnvironmentId": 10003
	} ]
}

The following snapshot object will then be created in FlexDeploy:

Code Block

title
theme	Eclipse

...

POST JSON

{
	"snapshotId": 10005,
	"snapshotName": "07-09-2018 12:

...

12:03",
	"description": "example snapshot creation",
	"snapshotStatus": "

...

PENDING",
	"snapshotVersions": [
	{
		"projectId": 10000,
		"packageName": "package1",
		"projectVersionId":

...

10001,
		"requestAllFiles": false,
		"snapshotVersionStatus": "EXISTING"
	},
	{
		"projectId": 10000,
		"packageName": "package2",
		"projectVersionId":

...

null,
		"requestAllFiles": false,
		"snapshotVersionStatus": "

...

PENDING"
	},
	{
		"projectId": 10002,
		"packageName": null,
		"projectVersionId":

...

null,
		"requestAllFiles": false,
		"snapshotVersionStatus": "

...

PENDING"
	}]
}

GET (Using Query Parameters)

...

POST (promote to release)

Project versions can be promoted to a release through this POST service. Promoting a project to release will combine the specified version of the specified project with the versions of the other projects used in the last snapshot into a new snapshot.

Info

title

...

URL for promoting a project version to a release

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

...

Request

...

/{releaseId}/snapshot

Request

POST will receive a snapshot input JSON object and return a snapshot JSON object. Snapshot input JSON objects can have the following attributes:

Attributes	Type	Required	Description
releaseId

...

URL

...

Yes

Path parameter for the release Id

...

where the snapshot will be

...

added
action	String

...

Yes	should be set to promoteToRelease for this API.
description	String	No	The description of the snapshot
snapshotVersionInputs	List<SnapshotVersionInputPojo>	Yes	One and only one element is required for promote to release action.

Elements of snapshotVersionInputs has following attributes:

Attributes	Type	Required	Description
projectId	Long	Yes	Project associated with release.
projectVersionId	Long	Yes	The version id of the project. If using packageName, version for package must be provided.
packageName	String	No	The name of the package (used for partial deployment projects only) associated with release. If Partial deployment project and packageName is not supplied it will be considered all files type version.

Response

Snapshot JSON objects can

...

having the following attributes:

...

Attributes	Type	Description
snapshotId	Long	The id of the snapshot
snapshotName

...

String

The name of the snapshot, which is

...

the time

...

when the snapshot was created

snapshotStatus

String

The status of the snapshot. Possible values are:

COMPLETED - The snapshot was successfully assembled, but has not yet been sent to pipeline for execution.
FAILED - The snapshot failed to be assembled (which could mean the underlying build failed).
FAILED TO INITIATE - The snapshot was assembled, but failed to be sent to the pipeline for execution.
INITIATED - The snapshot has been sent to the pipeline for execution.
PENDING - The snapshot is in the process of being assembled and

...

set to the pipeline for execution.
description	String	The description of the snapshot
snapshotVersions	List<SnapshotVersionPojo>	The version information about the projects

...

associated with the snapshot

Elements of snapshotVersions has

...

following attributes:

...

Attributes	Type	Description
projectId	Long	The id of the project
projectStreamId	Long	The id of the Stream which the project/package was built from.
projectVersionId	Long	The version id of the project
packageName	String	The name of the package (used for partial deployment projects only)
requestAllFiles	Boolean	Whether or not the project

...

was told to request all files
snapshotVersionStatus	String	The current status of the individual project version within the snapshot. Possible values are:

...

PENDING - The project is has not yet been built for the snapshot.
SUBMITTED - The project is currently being built for the snapshot.
COMPLETED - The project has been built successfully for the snapshot.
FAILED - The project has failed to build.
EXISTING - The snapshot is utilizing an already built version of the project.

Response Codes

HTTP Code	Description

...

201	Snapshot created
401	Authentication failure
403	Authorization failure (no access to resource)
404	Release not found
500	Unexpected internal server error

Example

If

...

Request: http://host:port/flexdeploy/rest/v1/releases/11211/snapshot?status=COMPLETED&limit=2

A GET request would be triggered and return the following JSON snapshots object:

...

theme	Eclipse
title	GET JSON Response

...

the previous snapshot had the following attributes:

Code Block

theme	Eclipse
title	Current JSON

{
	"snapshotId": 10005,
	"snapshotName": "07-09-2018 12:12:03",
	"description": "",
	"snapshotStatus": "INITIATED",
	"snapshotVersions": [
	{
		"projectId": 10000,
		"packageName": "package1",
		"projectVersionId": 10001,
		"requestAllFiles": false,
		"snapshotVersionStatus": "EXISTING"
	},
	{
		"projectId": 10000,
		"packageName": "package2",
		"projectVersionId": 10040,
		"requestAllFiles": false,
		"snapshotVersionStatus": "COMPLETED"
	},
	{
		"projectId":

...

10002,

...

		"packageName": null,

...

projectVersionId":

...

10065,

...

"requestAllFiles": false

...

"snapshotVersionStatus": "COMPLETED"

...


	}]
}

And a POST request was sent to http://host:port/flexdeploy/rest/v1/releases/{releaseId}/snapshot with the following JSON object input:

Code Block

theme	Eclipse
title	POST JSON

{
	"action" : "promoteToRelease",
    "description": "example snapshot creation",
	"snapshotVersionInputs": [
	{
		"projectId":

...

10000,

...

		"packageName": "

...

package1",

...

projectVersionId":

...

10025
	} ]
}

The following Snapshot JSON object will begin:

Code Block

theme	Eclipse
title	Response JSON

{
	"snapshotId": 10025,
	"snapshotName": "

...

07-

...

09-

...

12:15:03",
	"description": "",

...

snapshotStatus":

...

"INITIATED",

...

"snapshotVersions": [
	{
		"

...

projectId":

...

10000,
		"

...

packageName": "

...

package1",
		"

...

projectVersionId":

...

10025,

...

"requestAllFiles": false,
		"snapshotVersionStatus": "

...

EXISTING"

...

},
	{
		"projectId":

...

10000,

...

		"packageName":

...

"package2",

...

projectVersionId":

...

10040,

...

		"requestAllFiles": false

...

		"snapshotVersionStatus": "

...

EXISTING"

...

},
	{
		"projectId":

...

10002,

...

		"packageName": null,

...

projectVersionId":

...

10065,

...

		"requestAllFiles":

...

false,

...

"snapshotVersionStatus": "

...

EXISTING"
	}]
}

Versions Compared

Old Version 29

New Version 30

Key

GET

GET (By Id)

Request

Response

Response Codes

Example

Response

Response Codes

Example

POST (promote to release)

Request

Response

Response Codes

Example

GET (Using Query Parameters)

Request

Response

Response Codes

Example

GET (By Id)

Request

POST (create snapshot)

Request

Response

Response Codes

Example

GET (Using Query Parameters)

POST (promote to release)

Request

Request

Response

Response Codes

Example

Page Comparison

Versions Compared

Old Version 29

New Version 30

Key

GET

GET (By Id)

Request

Response

Response Codes

Example

Response

Response Codes

Example

POST (promote to release)

Request

Response

Response Codes

Example

GET (Using Query Parameters)

Request

Response

Response Codes

Example

GET (By Id)

Request

POST (create snapshot)

Request

Response

Response Codes

Example

GET (Using Query Parameters)

POST (promote to release)

Request

Request

Response

Response Codes

Example