Release Snapshot API

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

Authentication - Use Basic Authentication for this API.

POST (create snapshot)

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

API URL

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

Set the request header Content-Type to application/json.

Request

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

AttributesTypeRequiredDescription
releaseIdURLYesPath parameter for the release Id where the snapshot will be added
actionStringYes

should be set to createSnapshot for this API.

descriptionStringNoThe description of the snapshot
snapshotVersionInputsList<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.

Elements of snapshotVersionInputs has following attributes:

AttributesTypeRequiredDescription
projectIdLongYesProject associated with release.
projectVersionIdLongNoThe version id of the project. If project version is not supplied new build will be performed.
packageNameString

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.
buildEnvironmentIdLongNoThe build environment associated with the project. If not supplied and only one environment found for build instance then it will be defaulted.
forceBuildBooleanNoWhether 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:

AttributesTypeDescription

snapshotId

LongThe id of the snapshot
snapshotNameStringThe name of the snapshot, which is the time when the snapshot was created
snapshotStatusString

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.
descriptionStringThe description of the snapshot
snapshotVersionsList<SnapshotVersionPojo>The version information about the projects associated with the snapshot

Elements of snapshotVersions has following attributes:

AttributesTypeDescription
projectIdLongThe id of the project
projectStreamIdLongStream included in release for the project.
projectVersionIdLongThe version id of the project
packageNameStringThe name of the package (used for partial deployment projects only)
requestAllFilesBooleanWhether or not the project was told to request all files
snapshotVersionStatusString

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.

Example

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

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:

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.

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:

AttributesTypeRequiredDescription
releaseIdURLYesPath parameter for the release Id where the snapshot will be added
actionStringYesshould be set to promoteToRelease for this API.
descriptionStringNoThe description of the snapshot
snapshotVersionInputsList<SnapshotVersionInputPojo>YesOne and only one element is required for promote to release action.

Elements of snapshotVersionInputs has following attributes:

AttributesTypeRequiredDescription
projectIdLongYesProject associated with release.
projectVersionIdLongYesThe version id of the project. If using packageName, version for package must be provided.
packageNameStringNoThe 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:

AttributesTypeDescription

snapshotId

LongThe id of the snapshot
snapshotNameStringThe name of the snapshot, which is the time when the snapshot was created
snapshotStatusString

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.
descriptionStringThe description of the snapshot
snapshotVersionsList<SnapshotVersionPojo>The version information about the projects associated with the snapshot

Elements of snapshotVersions has following attributes:

AttributesTypeDescription
projectIdLongThe id of the project
projectStreamIdLongStream included in release for the project.
projectVersionIdLongThe version id of the project
packageNameStringThe name of the package (used for partial deployment projects only)
requestAllFilesBooleanWhether or not the project was told to request all files
snapshotVersionStatusString

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.

Example

If the previous snapshot had the following attributes:

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:

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

The following Snapshot JSON object will begin:

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 (retrieve snapshot)

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

Request

ParameterTypeRequiredDescription
snapshotIdURLYesPath parameter for the snapshot Id which is used to return a snapshot
releaseIdURLYesPath parameter for the release Id which contains the snapshot that will be returned

Response

Snapshot JSON objects can having the following attributes:

AttributesTypeDescription

snapshotId

LongThe id of the snapshot
snapshotNameStringThe name of the snapshot, which is the time when the snapshot was created
snapshotStatusString

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.
descriptionStringThe description of the snapshot
snapshotVersionsList<SnapshotVersionPojo>The version information about the projects associated with the snapshot

Elements of snapshotVersions has following attributes:

AttributesTypeDescription
projectIdLongThe id of the project
projectStreamIdLongStream included in release for the project.
projectVersionIdLongThe version id of the project
packageNameStringThe name of the package (used for partial deployment projects only)
requestAllFilesBooleanWhether or not the project was told to request all files
snapshotVersionStatusString

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 CodeDescription
200Snapshot was found and returned
400Bad request (Not found or snapshot wasn't in given releaseId)
401Unauthorized (User may not be signed in or user may not have read access to releases)
500Unexpected 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:

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"
	}]
}