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.
GET
There are two implementations of GET. One will find a Snapshot with the given release id and snapshot id and return the JSON representation of the Snapshot. The other will find a list of Snapshots matching the parameters supplied to it.
GET (By Id)
This GET service will return the JSON representation of a snapshot given a release id and snapshot Id.
Request
Parameter | Type | Required | Description |
---|---|---|---|
snapshotId | URL | Yes | Path parameter for the 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:
|
description | String | The description of the snapshot |
snapshotVersions | List<SnapshotVersionPojo> | The version information about the projects/packages contained within this snapshot |
snapshotVariables | List<SnapshotVariable> | The related snapshot variables |
links | List<Link> | List of any relevant links for the object. |
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) |
snapshotVersionStatus | String | The current status of the individual project version within the snapshot. Possible values are:
|
Elements of snapshotVariables has the following attributes:
Attribute | Type | Description |
---|---|---|
displayName | String | Display name |
code | String | Code for the variable |
description | String | Description of the variable |
dataType | String | Data type of the variable |
value | String | Value of the variable |
updatedBy | String | Who last updated this variable |
updatedOn | String | Last time the variable was updated |
Link
Attribute Type Description type String Type of the link "REST", "UI" link String Physical link of the object.
Link
Attribute | Type | Description |
---|---|---|
type | String | Type of the link "REST", "UI" |
link | String | Physical link of the object. |
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:
{ "snapshotId": 10005, "snapshotName": "07-09-2018 12:15:03", "description": "", "snapshotStatus": "INITIATED", "snapshotVersions": [ { "projectId": 10000, "packageName": "package1", "projectVersionId": 10025, "snapshotVersionStatus": "EXISTING" }, { "projectId": 10000, "packageName": "package2", "projectVersionId": 10040, "snapshotVersionStatus": "EXISTING" }, { "projectId": 10002, "packageName": null, "projectVersionId": 10065, "snapshotVersionStatus": "EXISTING" }], "snapshotVariables": [ { "value": "", "displayName": "Name", "description": "description", "dataType": "String", "code": "VARIABLE", "updatedBy": "fduser", "updatedOn": "07-02-2020 12:37:18" }], "links": [ { "type": "UI", "link": "http://host:port/flexdeploy/faces/releases?dashboard=true&relSnapshotId=10005&relDefinitionId=14321" } ] }
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.
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. |
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:
|
description | String | The description of the snapshot |
snapshotVersions | List<SnapshotVersionPojo> | The version information about the projects/packages contained within this snapshot |
snapshotVariables | List<SnapshotVariable> | The related snapshot variables |
links | List<Link> | List of any relevant links for the object. |
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) |
snapshotVersionStatus | String | The current status of the individual project version within the snapshot. Possible values are:
|
Elements of snapshotVariables have the following attributes:
Attribute | Type | Description |
---|---|---|
displayName | String | Display name |
code | String | Code for the variable |
description | String | Description of the variable |
dataType | String | Data type of the variable |
value | String | Value of the variable |
updatedBy | String | Who last updated this variable |
updatedOn | String | Last time the variable was updated |
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?snapshotStatus=COMPLETED&limit=2
A GET request would be triggered and return the following JSON snapshots object:
[ { "snapshotId": 11501, "snapshotStatus": "COMPLETED", "snapshotVersions": [ { "snapshotVersionStatus": "COMPLETED", "projectVersionId": 33129, "projectId": 25208, "packageName": null, "projectStreamId": 25209 }, { "snapshotVersionStatus": "COMPLETED", "projectVersionId": 33175, "projectId": 25228, "packageName": "Package1", "projectStreamId": 25229 }, { "snapshotVersionStatus": "COMPLETED", "projectVersionId": 33146, "projectId": 25228, "packageName": "Package2", "projectStreamId": 25229 } ], "snapshotName": "02-08-2019 08:52:02", "description": null, "snapshotVariables": [ { "value": "", "displayName": "Name", "description": "description", "dataType": "String", "code": "VARIABLE", "updatedBy": "fduser", "updatedOn": "07-02-2020 12:37:18" }] }, { "snapshotId": 11346, "snapshotStatus": "COMPLETED", "snapshotVersions": [ { "snapshotVersionStatus": "COMPLETED", "projectVersionId": 32466, "projectId": 25208, "packageName": null, "projectStreamId": 25209 }, { "snapshotVersionStatus": "COMPLETED", "projectVersionId": 32436, "projectId": 25228, "packageName": null, "projectStreamId": 25229 } ], "snapshotName": "02-06-2019 16:35:04", "description": null, "snapshotVariables": [] } ]
POST (create snapshot)
This POST service will create a new snapshot with the same attributes as the given JSON object.
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 |
|
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, a 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 a Partial deployment project is supplied with a packageName, an exception will be thrown. |
buildEnvironmentId | Long | No | The build environment associated with the project. If not supplied and only one environment is found for build instance then it will be defaulted. |
forceBuild | Boolean | No | Whether or not the project should be force built. Partial deployment projects are always force built. |
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:
|
description | String | The description of the snapshot |
snapshotVersions | List<SnapshotVersionPojo> | The version information about the projects associated with the snapshot |
snapshotVariables | List<SnapshotVariable> | The related snapshot variables |
links | List<Link> | List of any relevant links for the object. |
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) |
snapshotVersionStatus | String | The current status of the individual project version within the snapshot. Possible values are:
|
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,
{ "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:
{ "snapshotId": 10005, "snapshotName": "07-09-2018 12:12:03", "description": "example snapshot creation", "snapshotStatus": "PENDING", "snapshotVersions": [ { "projectId": 10000, "packageName": "package1", "projectVersionId": 10001, "snapshotVersionStatus": "EXISTING" }, { "projectId": 10000, "packageName": "package2", "projectVersionId": null, "snapshotVersionStatus": "PENDING" }, { "projectId": 10002, "packageName": null, "projectVersionId": null, "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
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 a Partial deployment project is supplied with a packageName, an exception will be thrown. |
The build environment associated with the project. If not supplied and only one environment is found for build instance then it will be defaulted. |
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:
|
description | String | The description of the snapshot |
snapshotVersions | List<SnapshotVersionPojo> | The version information about the projects associated with the snapshot |
snapshotVariables | List<SnapshotVariable> | The related snapshot variables |
links | List<Link> | List of any relevant links for the object. |
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) |
snapshotVersionStatus | String | The current status of the individual project version within the snapshot. Possible values are:
|
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 previous snapshot had the following attributes:
{ "snapshotId": 10005, "snapshotName": "07-09-2018 12:12:03", "description": "", "snapshotStatus": "INITIATED", "snapshotVersions": [ { "projectId": 10000, "packageName": "package1", "projectVersionId": 10001, "snapshotVersionStatus": "EXISTING" }, { "projectId": 10000, "packageName": "package2", "projectVersionId": 10040, "snapshotVersionStatus": "COMPLETED" }, { "projectId": 10002, "packageName": null, "projectVersionId": 10065, "snapshotVersionStatus": "COMPLETED" }] }
And a POST request was sent to http://host:port/flexdeploy/rest/v1/releases/{releaseId}/snapshot with the following JSON object input:
{ "action" : "promoteToRelease", "description": "example snapshot creation", "snapshotVersionInputs": [ { "projectId": 10000, "packageName": "package1", "projectVersionId": 10025 } ] }
The following Snapshot JSON object will begin:
{ "snapshotId": 10025, "snapshotName": "07-09-2018 12:15:03", "description": "", "snapshotStatus": "INITIATED", "snapshotVersions": [ { "projectId": 10000, "packageName": "package1", "projectVersionId": 10025, "snapshotVersionStatus": "EXISTING" }, { "projectId": 10000, "packageName": "package2", "projectVersionId": 10040, "snapshotVersionStatus": "EXISTING" }, { "projectId": 10002, "packageName": null, "projectVersionId": 10065, "snapshotVersionStatus": "EXISTING" }] }
- style