Kwatee REST API version 4.0.2

Mapping of URIs that begin with /kwatee/api

REST Commands Summary
Login

Authenticates a user

Logout

Logs current user out

GetArtifacts

Retrieves the list of artifacts in the repository

GetArtifact

Retrieves an artifact's properties

UpdateArtifact

Updates an artifact's properties

CreateArtifact

Creates a new artifact and optionally set additional properties

DeleteArtifact

Deletes an artifact

GetVersion

Retrieves the properties of an artifact's version

UpdateVersion

Updates an artifact's version properties

CreateOrDuplicateVersion

Creates or duplicates a version in an artifact and optionally set additional properties

DeleteVersion

Deletes an artifact's version

UploadArtifactPackage

Uploads a package to an artifact's version

UploadArtifactPackage

Uploads a package to an artifact's version

DeleteArtifactPackage

Deletes an existing version package

GetArtifactPackageFiles

Retrieves the files present in a version's package at a given relative path

GetArtifactSpecialFiles

Retrieves all the special files within the package

UpdateArtifactPackageFileProperties

Updates custom flags of a file within a package

DownloadArtifactPackageFile

Downloads a file within the package in the specified location

UploadArtifactPackageOverlay

Uploads an overlay at a relative path within the package

UploadArtifactPackageOverlay

Uploads an overlay at a relative path within the package

DeleteArtifactPackageOverlay

Deletes an existing version overlay

GetArtifactVariables

Retrieves the list of version variables

SetArtifactVariables

Sets version variables

SetArtifactVariablePrefixCharacter

Sets the version's variable prefix character

GetServers

Retrieves the list of servers in the repository

GetServer

Retrieves server properties

UpdateServer

Updates the properties of a server

CreateOrDuplicateServer

Creates or duplicates a server and optionally set additional properties

DeleteServer

Deletes a server

ServerDiagnostics

Tests a connection to the server and returns server capabilities

GetEnvironments

Retrieves the list of environments in the repository

GetEnvironment

Retrieves an environment's properties

UpdateEnvironment

Updates the environment with new properties

CreateOrDuplicateEnvironment

Creates or duplicates an environment and optionally set additional properties

DeleteEnvironment

Deletes an environment

GetRelease

Retrieve an environment's release properties

UpdateRelease

Updates a release with new properties

TagRelease

Tags a release and optionally sets additional properties

DeleteRelease

Deletes a release

ReeditRelease

Reedits a previously tagged release

GetEffectiveReleaseArtifacts

Retrieves the effective release artifacts

SetReleaseArtifactActiveVersion

Sets the active version (default of server-specific) of a release artifact

GetReleasePackageFiles

Retrieves the files present in an release artifact package at a given relative path within the package

GetReleaseSpecialFiles

Retrieves all the special files within the release artifact package

UpdateReleasePackageFileProperties

Update custom flags of a file within a release artifact package

DownloadReleasePackageFile

Downloads a file within the release artifact package

UploadReleasePackageOverlay

Uploads an overlay at a relative path within the release artifact package

UploadReleasePackageOverlay

Uploads an overlay at a relative path within the release artifact package

DeleteReleasePackageOverlay

Deletes an existing release artifact package overlay

GetReleaseVariables

Retrieves release variables

SetReleaseVariables

Sets the release variables

GetDeployments

Retrieves the list of deployments

GetDeployment

Retrieves the deployment properties

DownloadLightweightInstaller

Downloads a self-contained command-line installer (to install one server at a time)

DownloadInstaller

Downloads an installer

ManageDeploy

Initiates a deploy operation

ManageUndeploy

Initiates an undeploy operation

ManageCheckIntegrity

Initiates a check integrity operation

ManageStart

Initiates a start executables operation

ManageStop

Initiates a stop executables operation

ManageStatus

Initiates an executables status operation

GetOngoingOperation

Retrieves an ongoing deployment operation

hasOperationCompleted

Is an ongoing operation in progress?

GetOperationProgress

Retrieves the progress of a deployment operation

GetProgressMessages

Retrieves the details of a deployment operation for a given server and or artifact

ManageCancel

Cancels an ongoing operation

SendCredentials

Supply server credentials without storing them in kwatee

GetInfoContext

Retrieves kwatee information

GetInfoPlatforms

Retrieves the available platforms

GetInfoConduitTypes

Retrieves the available conduit types

GetInfoServerPoolTypes

Retrieves the available server pool types

Login

POST /kwatee/api/authenticate/{userName}

Authenticates a user. The password is expected in the X-API-AUTH http headers.

Parameters

Name Description Type Mandatory
PathVariable userName the user to authenticate String true
RequestParam version the api version String false

Response

Returns text/plain encoded authentication token

Example

Set HTTP header: X-API-AUTH=password

Request POST http://kwatee.local:8080/kwate/api/authenticate/admin
Response 200
WBqmpTYhcMM22hg5-HrFAxC-cTt3ec8BubiqR...

Logout

POST /kwatee/api/logout

Logs current user out.

Response

Example

Request POST http://kwatee.local:8080/kwate/api/logout
Response 200

GetArtifacts

GET /kwatee/api/artifacts.json

Retrieves the list of artifacts in the repository.

Response

Returns application/json array of artifact objects

Example

Request GET http://kwatee.local:8080/kwate/api/artifacts.json?activeOnly=true
Response 200
[
  {
    "description" : "Demo PHP web site",
    "name" : "demowebsite"
  }
]

GetArtifact

GET /kwatee/api/artifacts/{artifactName}.json

Retrieves an artifact's properties.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of an artifact String true

Response

Returns application/json artifact object

Example

Request GET http://kwatee.local:8080/kwate/api/artifacts/demowebsite.json
Response 200
{
  "name" : "demowebsite",
  "description" : "Demo PHP web site",
  "versions" : [
    {
      "name" : "1.0",
      "description" : "initial release",
      "platforms" : [1, 2, 7]
    }
  ]
}

UpdateArtifact

PUT /kwatee/api/artifacts/{artifactName}

Updates an artifact's properties.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of an artifact String true
RequestBody artifactProperties the JSON artifact's properties to update String true

Response

Example

Request PUT http://kwatee.local:8080/kwate/api/artifacts/demowebsite
{
  "description" : "new description"
}
Response 200

CreateArtifact

POST /kwatee/api/artifacts/{artifactName}

Creates a new artifact and optionally set additional properties.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the artifact to create String true
RequestBody artifactProperties the JSON artifact's properties to update or empty String true

Response

Example

Request POST http://kwatee.local:8080/kwate/api/artifacts/testArtifact
{
  "description" : "initial description"
}
Response 201

DeleteArtifact

DELETE /kwatee/api/artifacts/{artifactName}

Deletes an artifact. The operation is successful even if the artifact does not exist.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of an artifact String true

Response

Example

Request DELETE http://kwatee.local:8080/kwate/api/artifacts/testArtifact
Response 200

GetVersion

GET /kwatee/api/artifacts/{artifactName}/{versionName}.json

Retrieves the properties of an artifact's version.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of a version String true

Response

Returns application/json version object

Example

Request GET http://kwatee.local:8080/kwate/api/artifacts/demowebsite/1.0.json
Response 200
{
  "name" : "1.0",
  "description" : "initial release",
  "frozen" : true,
  "platforms" : [1, 2, 7],
  "packageInfo" : {
    "name" : "mywebsite.zip",
    "size" : "10.0 KB"
  },
  "executables" : [],
  "varPrefixChar" : 37
}

UpdateVersion

PUT /kwatee/api/artifacts/{artifactName}/{versionName}

Updates an artifact's version properties.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of a version String true
RequestBody versionProperties the JSON version properties String true

Response

Example

Request PUT http://kwatee.local:8080/kwate/api/artifacts/demowebsite/1.0
{
  "description" : "new description"
}
Response 200

CreateOrDuplicateVersion

POST /kwatee/api/artifacts/{artifactName}/{versionName}

Creates or duplicates a version in an artifact and optionally set additional properties.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of the version to create String true
RequestParam duplicateFrom the optional name of a version to duplicate String false
RequestBody versionProperties the optional JSON version properties String true

Response

Example

Duplicate existing version 1.0

Request POST http://kwatee.local:8080/kwate/api/artifacts/demowebsite/2.0?duplicateFrom=1.0
{
  "description" : "duplicated from version 1.0"
}
Response 201

DeleteVersion

DELETE /kwatee/api/artifacts/{artifactName}/{versionName}

Deletes an artifact's version. The operation is successful even if the version does not exist.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of a version String true

Response

Example

Request DELETE http://kwatee.local:8080/kwate/api/artifacts/demowebsite/2.0
Response 200

UploadArtifactPackage

POST /kwatee/api/artifacts/{artifactName}/{versionName}/package

Uploads a package to an artifact's version.
Replaces whatever existing package there is but retains previously uploaded overlays unless deleteOverlays=true.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of a version String true
RequestParam file the package file to upload as POST data MultipartFile false
RequestParam deleteOverlays if true, removes pre-existing overlays ( false if omitted) boolean false

Response

Example

Request POST http://kwatee.local:8080/kwate/api/artifacts/demowebsite/1.0
multipart/form-data: ...Content-Disposition: form-data; name="file";filename="newarchive.tar.gz"
Response 200

UploadArtifactPackage

POST /kwatee/api/artifacts/{artifactName}/{versionName}/package

Uploads a package to an artifact's version.
Replaces whatever existing package there is but retains previously uploaded overlays unless deleteOverlays=true.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of a version String true
RequestParam url url or server path of package to upload String false
RequestParam deleteOverlays if true, removes pre-existing overlays ( false if omitted) boolean false

Response

Example

Request POST http://kwatee.local:8080/kwate/api/artifacts/demowebsite/1.0?url=file:///newarchive.tar.gz
Response 200

DeleteArtifactPackage

DELETE /kwatee/api/artifacts/{artifactName}/{versionName}/package

Deletes an existing version package.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of a version String true

Response

Example

Request DELETE http://kwatee.local:8080/kwate/api/artifacts/demowebsite/1.0/package
Response 200

GetArtifactPackageFiles

GET /kwatee/api/artifacts/{artifactName}/{versionName}/package/files.json

Retrieves the files present in a version's package at a given relative path.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of a version String true
RequestParam path the relative path of the directory to list within package (if omitted, root of the package) String false

Response

Returns application/json array of file objects

Example

Request GET http://kwatee.local:8080/kwate/api/artifacts/demowebsite/1.0/package/files.json
Response 200
[
  {
    "id" : 1,
    "name" : "index.php",
    "hasVariables" : true
  },
  {
    "id" : 2,
    "name" : "logo.gif"
  }
]

GetArtifactSpecialFiles

GET /kwatee/api/artifacts/{artifactName}/{versionName}/package/specialFiles.json

Retrieves all the special files within the package. Files with custom properties, containing variables or overlays are considered "special".

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of a version String true

Response

Returns application/json array of file objects

Example

Request GET http://kwatee.local:8080/kwate/api/artifacts/demowebsite/1.0/package/specialFiles.json
Response 200
[
  {
    "id" : 1,
    "name" : "index.php",
    "hasVariables" : true,
    "path" : "index.php"
  }
]

UpdateArtifactPackageFileProperties

PUT /kwatee/api/artifacts/{artifactName}/{versionName}/package/file

Updates custom flags of a file within a package.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of a version String true
RequestParam path the relative path of the file within the package String false
RequestBody fileProperties the JSON file's properties to update String true

Response

Example

Request PUT http://kwatee.local:8080/kwate/api/artifacts/demowebsite/1.0/package/file?path=index.php
{
  "ignoreVariables" : true
}
Response 200

DownloadArtifactPackageFile

GET /kwatee/api/artifacts/{artifactName}/{versionName}/package/file

Downloads a file within the package in the specified location.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of a version String true
RequestParam path the relative path of the file within the package String false

Response

Returns text/plain or application/octet-stream file contents

Example

Request GET http://kwatee.local:8080/kwate/api/artifacts/demowebsite/1.0/package/file?path=index.php
Response 200

UploadArtifactPackageOverlay

POST /kwatee/api/artifacts/{artifactName}/{versionName}/package/overlay

Uploads an overlay at a relative path within the package.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of a version String true
RequestParam path the relative path of the overlay directory within the package String false
RequestParam file overlay file to upload as POST data MultipartFile false

Response

Example

Upload an overlay at the root of the archive named 'logo.gif'

Request POST http://kwatee.local:8080/kwate/api/artifacts/demowebsite/1.0/package/overlay
Response 201

UploadArtifactPackageOverlay

POST /kwatee/api/artifacts/{artifactName}/{versionName}/package/overlay

Uploads an overlay at a relative path within the package.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of a version String true
RequestParam path the relative path of the overlay directory within the package String false
RequestParam url url or server path of overlay file to upload String false

Response

Example

Upload an overlay at the root of the archive named 'logo.gif'

Request POST http://kwatee.local:8080/kwate/api/artifacts/demowebsite/1.0/package/overlay?url=file:///logo.gif
Response 201

DeleteArtifactPackageOverlay

DELETE /kwatee/api/artifacts/{artifactName}/{versionName}/package/overlay

Deletes an existing version overlay.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of a version String true
RequestParam path the relative path of the file within the package String false

Response

Example

Request DELETE http://kwatee.local:8080/kwate/api/artifacts/demowebsite/1.0/package/overlay?path=logo.gif
Response 200

GetArtifactVariables

GET /kwatee/api/artifacts/{artifactName}/{versionName}/variables.json

Retrieves the list of version variables.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of a version String true

Response

Returns application/json array of version variable objects

Example

Request GET http://kwatee.local:8080/kwate/api/artifacts/demowebsite/1.0/variables.json
Response 200
[
  {
    "name" : "CUSTOMER_NAME",
    "reference" : ["demowebsite - index.php"]
  }
]

SetArtifactVariables

PUT /kwatee/api/artifacts/{artifactName}/{versionName}/variables

Sets version variables.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of a version String true
RequestBody variables a JSON array of variable objects String true

Response

Example

Request PUT http://kwatee.local:8080/kwate/api/artifacts/demowebsite/1.0/variables
[
  {
    "name" : "CUSTOMER_NAME",
    "value" : "ACME Corp."
  }
]
Response 200

SetArtifactVariablePrefixCharacter

PUT /kwatee/api/artifacts/{artifactName}/{versionName}/variablePrefix

Sets the version's variable prefix character.

Parameters

Name Description Type Mandatory
PathVariable artifactName the name of the version's artifact String true
PathVariable versionName the name of a version String true
RequestParam char char false

Response

Example

Request PUT http://kwatee.local:8080/kwate/api/artifacts/demowebsite/1.0/variablePrefix?char=@
Response 200

GetServers

GET /kwatee/api/servers.json

Retrieves the list of servers in the repository

Response

Returns application/json array of server objects

Example

Request GET http://kwatee.local:8080/kwate/api/servers.json
Response 200
[
  {
    "name" : "demoserver",
    "description" : "Demo server"
  }
]

GetServer

GET /kwatee/api/servers/{serverName}.json

Retrieves server properties.

Parameters

Name Description Type Mandatory
PathVariable serverName the name of the server String true

Response

Returns application/json server object

Example

Request GET http://kwatee.local:8080/kwate/api/servers/demoserver.json
Response 200
{
  "name" : "demoserver",
  "description" : "Demo server",
  "platform" : 2,
  "conduitType" : "ssh",
  "ipAddress" : "demo.kwatee.net",
  "port" : 22,
  "credentials" : {
    "login" : "kwtest"
  },
  "properties" : {},
  "poolConcurrency" : 0
}

UpdateServer

PUT /kwatee/api/servers/{serverName}

Updates the properties of a server.

Parameters

Name Description Type Mandatory
PathVariable serverName the name of the server String true
RequestBody serverProperties the JSON server properties to update String true

Response

Example

Request PUT http://kwatee.local:8080/kwate/api/servers/demoserver
Response 200

CreateOrDuplicateServer

POST /kwatee/api/servers/{serverName}

Creates or duplicates a server and optionally set additional properties.

Parameters

Name Description Type Mandatory
PathVariable serverName the name of the server to create String true
RequestParam duplicateFrom the optional name of a server to duplicate String false
RequestBody serverProperties the optional JSON server properties String true

Response

Example

Request POST http://kwatee.local:8080/kwate/api/servers/newserver
Response 201

DeleteServer

DELETE /kwatee/api/servers/{serverName}

Deletes a server. The operation is successful even if the server does not exist.

Parameters

Name Description Type Mandatory
PathVariable serverName the name of the server String true

Response

Example

Request DELETE http://kwatee.local:8080/kwate/api/servers/newserver
Response 200

ServerDiagnostics

POST /kwatee/api/servers/{serverName}/testConnection

Tests a connection to the server and returns server capabilities.

Parameters

Name Description Type Mandatory
PathVariable serverName the name of the server String true
RequestBody json String true

Response

Returns application/json array of server capabilities

Example

Request POST http://kwatee.local:8080/kwate/api/servers/demoserver
Response 200
[
  "Test platform command availability (support=0 is good)",
  "cd support=0",
  "chmod support=0",
  "mkdir support=0",
  "rm support=0",
  "cat support=0"
]

GetEnvironments

GET /kwatee/api/environments.json

Retrieves the list of environments in the repository.

Response

Returns application/json array of environment objects

Example

Request GET http://kwatee.local:8080/kwate/api/environments.json
Response 200
[
  {
    "name" : "intro",
    "description" : "introductory tutorial"
  }
]

GetEnvironment

GET /kwatee/api/environments/{environmentName}.json

Retrieves an environment's properties.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the environment String true

Response

Returns application/json environment object

Example

Request GET http://kwatee.local:8080/kwate/api/environments/intro.json
Response 200
{
  "name" : "intro",
  "description" : "introductory tutorial",
  "artifacts" : ["demowebsite"],
  "servers" : ["demoserver"],
  "sequentialDeployment" : true,
  "releases" : [
    {
      "name" : "snapshot",
      "editable" : true
    },
    {
      "name" : "acme-1.0",
      "description" : "initial deployment"
    }
  ]
}

UpdateEnvironment

PUT /kwatee/api/environments/{environmentName}

Updates the environment with new properties.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of an environment String true
RequestBody environmentProperties the JSON environment properties to update String true

Response

Example

Request PUT http://kwatee.local:8080/kwate/api/environments/intro
{
  "description" : "new description"
}
Response 200

CreateOrDuplicateEnvironment

POST /kwatee/api/environments/{environmentName}

Creates or duplicates an environment and optionally set additional properties.
Note that only the snapshot environment is included in a duplicate operation.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the environment to create String true
RequestParam duplicateFrom the optional name of an environment to duplicate String false
RequestBody environmentProperties the optional JSON environment properties String true

Response

Example

Request POST http://kwatee.local:8080/kwate/api/environments/testEnvironment
{
  "description" : "initial description"
}
Response 201

DeleteEnvironment

DELETE /kwatee/api/environments/{environmentName}

Deletes an environment. The operation is successful even if the environment does not exist.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of an environment String true

Response

Example

Request DELETE http://kwatee.local:8080/kwate/api/environments/testEnvironment
Response 200

GetRelease

GET /kwatee/api/environments/{environmentName}/{releaseName}.json

Retrieve an environment's release properties.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true

Response

Returns application/json release object

Example

Request GET http://kwatee.local:8080/kwate/api/environments/intro/snapshot.json
Response 200
{
  "name" : "snapshot",
  "editable" : true,
  "defaultArtifacts" : [
    {
      "artifact" : "demowebsite",
      "version" : "1.0"
    }
  ],
  "serverArtifacts" : [
    {
      "server" : "demoserver",
      "artifacts" : [
        {
          "artifact" : "demowebsite"
        }
      ]
    }
  ]
}

UpdateRelease

PUT /kwatee/api/environments/{environmentName}/{releaseName}

Updates a release with new properties.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true
RequestBody json String true

Response

Example

Request PUT http://kwatee.local:8080/kwate/api/environments/intro/snapshot
{
  "description" : "new description"
}
Response 200

TagRelease

POST /kwatee/api/environments/{environmentName}/{releaseName}

Tags a release and optionally sets additional properties.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of tagged release to create String true
RequestBody releaseProperties the optional JSON release properties to set String true

Response

Example

Request POST http://kwatee.local:8080/kwate/api/environments/intro/newtag
{
  "description" : "tagged on Oct 5, 2014"
}
Response 201

DeleteRelease

DELETE /kwatee/api/environments/{environmentName}/{releaseName}

Deletes a release. The operation is successful even if the release does not exist.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true

Response

Example

Request DELETE http://kwatee.local:8080/kwate/api/environments/intro/newtag
Response 200

ReeditRelease

POST /kwatee/api/environments/{environmentName}/{releaseName}/reedit

Reedits a previously tagged release.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true

Response

Example

Request POST http://kwatee.local:8080/kwate/api/environments/intro/newtag/reedit
Response 200

GetEffectiveReleaseArtifacts

GET /kwatee/api/environments/{environmentName}/{releaseName}/artifacts.json

Retrieves the effective release artifacts.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true

Response

Returns application/json array of release artifact objects

Example

Request GET http://kwatee.local:8080/kwate/api/environments/intro/snapshot/artifacts.json
Response 200
[
  {
    "artifact" : "demowebsite",
    "version" : "1.0"
  }
]

SetReleaseArtifactActiveVersion

PUT /kwatee/api/environments/{environmentName}/{releaseName}/activeVersion

Sets the active version (default of server-specific) of a release artifact.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true
RequestParam artifactName the name of an artifact String true
RequestParam versionName the active version to be set String true
RequestParam serverName an optional server name (omit to set default active version) String false

Response

Example

Request PUT http://kwatee.local:8080/kwate/api/environments/intro/snapshot/activeVersion?artifactName=demowebsite&versionName=1.0
Response 200

GetReleasePackageFiles

GET /kwatee/api/environments/{environmentName}/{releaseName}/package/files.json

Retrieves the files present in an release artifact package at a given relative path within the package.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true
RequestParam artifactName the name of an artifact String false
RequestParam serverName an optional server name (omit for listing files common to all servers overlays) String false
RequestParam path the optional relative path of the directory to list within package (omit for full recursive listing) String false

Response

Returns application/json array of file objects

Example

Request GET http://kwatee.local:8080/kwate/api/environments/intro/snapshot/package/files.json?artifactName=demowebsite
Response 200
[
  {
    "id" : 1,
    "name" : "index.php",
    "hasVariables" : true
  },
  {
    "id" : 2,
    "name" : "logo.gif"
  }
]

GetReleaseSpecialFiles

GET /kwatee/api/environments/{environmentName}/{releaseName}/package/specialFiles.json

Retrieves all the special files within the release artifact package. Files with custom properties, containing variables or overlays are considered "special".

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true
RequestParam artifactName the name of an artifact String false
RequestParam serverName an optional server name (omit for listing files common to all servers overlays) String false

Response

Returns application/json array of file objects

Example

Request GET http://kwatee.local:8080/kwate/api/environments/intro/snapshot/package/specialFiles.json?artifactName=demowebsite
Response 200
[
  {
    "id" : 1,
    "name" : "index.php",
    "hasVariables" : true
  },
  {
    "id" : 2,
    "name" : "logo.gif"
  }
]

UpdateReleasePackageFileProperties

PUT /kwatee/api/environments/{environmentName}/{releaseName}/package/file

Update custom flags of a file within a release artifact package.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true
RequestParam artifactName the name of an artifact String false
RequestParam serverName an optional server name (omit for making changes common to all servers) String false
RequestParam path the relative path of the file within the package String false
RequestBody fileProperties the JSON file properties to update String true

Response

Example

Request PUT http://kwatee.local:8080/kwate/api/environments/intro/snapshot/package/file?artifactName=demowebsite&path=index.php
{
  "ignoreVariables" : true
}
Response 200

DownloadReleasePackageFile

GET /kwatee/api/environments/{environmentName}/{releaseName}/package/file

Downloads a file within the release artifact package.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true
RequestParam artifactName the name of an artifact String false
RequestParam serverName an optional server name (omit for referring to common environment file) String false
RequestParam path the relative path of the file within the package String false

Response

Returns text/plain or application/octet-stream contents of the file

Example

Request GET http://kwatee.local:8080/kwate/api/environments/intro/snapshot/package/file?artifactName=demowebsite&path=index.php
Response 200

UploadReleasePackageOverlay

POST /kwatee/api/environments/{environmentName}/snapshot/package/overlay

Uploads an overlay at a relative path within the release artifact package.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
RequestParam artifactName the name of an artifact String false
RequestParam serverName an optional server name (omit for referring to common environment file) String false
RequestParam path the relative path of the overlay directory within the package String false
RequestParam file overlay file to upload as POST data MultipartFile false

Response

Example

Request POST http://kwatee.local:8080/kwate/api/environments/intro/snapshot/package/overlay?artifactName=demowebsite
multipart/form-data: ...Content-Disposition: form-data; name="file";filename="logo.gif"
Response 201

UploadReleasePackageOverlay

POST /kwatee/api/environments/{environmentName}/snapshot/package/overlay

Uploads an overlay at a relative path within the release artifact package.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
RequestParam artifactName the name of an artifact String false
RequestParam serverName an optional server name (omit for referring to common environment file) String false
RequestParam path the relative path of the overlay directory within the package String false
RequestParam url url or server path of overlay file to upload String false

Response

Example

Request POST http://kwatee.local:8080/kwate/api/environments/intro/snapshot/package/overlay?artifactName=demowebsite
multipart/form-data: ...Content-Disposition: form-data; name="file";filename="logo.gif"
Response 201

DeleteReleasePackageOverlay

DELETE /kwatee/api/environments/{environmentName}/snapshot/package/overlay

Deletes an existing release artifact package overlay.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
RequestParam artifactName the name of an artifact String false
RequestParam serverName an optional server name (omit for referring to common environment file) String false
RequestParam path the relative path of the file within the package String false

Response

Example

Request DELETE http://kwatee.local:8080/kwate/api/environments/intro/snapshot/package/overlay?artifactName=demowebsite&path=logo.gif
Response 200

GetReleaseVariables

GET /kwatee/api/environments/{environmentName}/{releaseName}/variables.json

Retrieves release variables.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true

Response

Returns application/json array of variable objects

Example

Request GET http://kwatee.local:8080/kwate/api/environments/intro/snapshot/variables.json
Response 200
{variables: [{name: 'CUSTOMER_NAME', value: 'ACME Corp.'}, {name: 'kwatee_deployment_dir', description: 'Default deployment directory', artifact: 'demowebsite', value: '/Library/WebServer/Documents'}], globalVariables: [{name: 'kwatee_root_dir', description: 'Kwatee agent
                      and metadata directory', value: '/var/tmp/kwatee'}, {name: 'kwatee_deployment_dir', description: 'Default deployment directory', value: '/var/tmp/kwateetest/%{kwatee_environment_name}'}, {name: 'kwatee_package_dir', description: 'Default deployment artifact directory',
                      value: '%{kwatee_deployment_dir}/%{kwatee_package_name}'}]}

SetReleaseVariables

PUT /kwatee/api/environments/{environmentName}/{releaseName}/variables

Sets the release variables.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true
RequestBody variables a JSON array of variable objects String true

Response

Example

Request PUT http://kwatee.local:8080/kwate/api/environments/intro/snapshot/variables
[
  {
    "name" : "CUSTOMER_NAME",
    "value" : "test"
  }
]
Response 200

GetDeployments

GET /kwatee/api/deployments.json

Retrieves the list of deployments.

Response

Returns application/json array of deployments objectes

Example

Request GET http://kwatee.local:8080/kwate/api/deployments.json
Response 200
[
  {
    "name" : "intro",
    "description" : "introductory tutorial",
    "releases" : [
      {
        "name" : "snapshot",
        "editable" : true
      },
      {
        "name" : "acme-1.0",
        "description" : "initial deployment"
      }
    ]
  }
]

GetDeployment

GET /kwatee/api/deployments/{environmentName}/{releaseName}.json

Retrieves the deployment properties.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true

Response

Returns application/json deployment object

Example

Request GET http://kwatee.local:8080/kwate/api/deployments/intro/snapshot.json
Response 200
{
  "name" : "snapshot",
  "serverArtifacts" : [
    {
      "server" : "demoserver",
      "artifacts" : [
        {
          "artifact" : "demowebsite",
          "version" : "1.0"
        }
      ]
    }
  ],
  "editable" : true
}

DownloadLightweightInstaller

GET /kwatee/api/deployments/{environmentName}/{releaseName}/installer_lightweight.tar.gz

Downloads a self-contained command-line installer (to install one server at a time).

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true

Response

Returns application/x-gtar installer

Example

Request GET http://kwatee.local:8080/kwate/api/deployments/intro/snapshot/_installer_lightweight.tar.gz
Response 200

DownloadInstaller

GET /kwatee/api/deployments/{environmentName}/{releaseName}/installer_cli.tar.gz

Downloads an installer.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true

Response

Returns application/x-gtar installer

Example

Request GET http://kwatee.local:8080/kwate/api/deployments/intro/snapshot/installer_cli.tar.gz
Response 200

ManageDeploy

POST /kwatee/api/deployments/{environmentName}/{releaseName}/deploy

Initiates a deploy operation.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true
RequestParam serverName the optional name of a server (omit to perform operation on all environment servers) String false
RequestParam artifactName the optional name of an artifact (omit to perform operation on all environment artifacts) String false

Response

Returns application/json deployment operation reference

Example

Request POST http://kwatee.local:8080/kwate/api/deployments/intro/deploy
Response 202
{
  "ref" : "1:1417387427690"
}

ManageUndeploy

POST /kwatee/api/deployments/{environmentName}/{releaseName}/undeploy

Initiates an undeploy operation.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true
RequestParam serverName the optional name of a server (omit to perform operation on all environment servers) String false
RequestParam artifactName the optional name of an artifact (omit to perform operation on all environment artifacts) String false
RequestParam forcedUndeploy when true forces undeploy even if there are errors (false if omitted) boolean false

Response

Returns application/json deployment operation reference

Example

Request POST http://kwatee.local:8080/kwate/api/deployments/intro/undeploy
Response 202
{
  "ref" : "1:1417387427690"
}

ManageCheckIntegrity

POST /kwatee/api/deployments/{environmentName}/{releaseName}/check

Initiates a check integrity operation.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true
RequestParam serverName the optional name of a server (omit to perform operation on all environment servers) String false
RequestParam artifactName the optional name of an artifact (omit to perform operation on all environment artifacts) String false

Response

Returns application/json deployment operation reference

Example

Request POST http://kwatee.local:8080/kwate/api/deployments/intro/check
Response 202
{
  "ref" : "1:1417387427690"
}

ManageStart

POST /kwatee/api/deployments/{environmentName}/{releaseName}/start

Initiates a start executables operation.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true
RequestParam serverName the optional name of a server (omit to perform operation on all environment servers) String false
RequestParam artifactName the optional name of an artifact (omit to perform operation on all environment artifacts) String false

Response

Returns application/json deployment operation reference

Example

Request POST http://kwatee.local:8080/kwate/api/deployments/intro/start
Response 202
{
  "ref" : "1:1417387427690"
}

ManageStop

POST /kwatee/api/deployments/{environmentName}/{releaseName}/stop

Initiates a stop executables operation.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true
RequestParam serverName the optional name of a server (omit to perform operation on all environment servers) String false
RequestParam artifactName the optional name of an artifact (omit to perform operation on all environment artifacts) String false

Response

Returns application/json deployment operation reference

Example

Request POST http://kwatee.local:8080/kwate/api/deployments/intro/stop
Response 202
{
  "ref" : "1:1417387427690"
}

ManageStatus

POST /kwatee/api/deployments/{environmentName}/{releaseName}/status

Initiates an executables status operation.

Parameters

Name Description Type Mandatory
PathVariable environmentName the name of the release's environment String true
PathVariable releaseName the name of the release String true
RequestParam serverName the optional name of a server (omit to perform operation on all environment servers) String false
RequestParam artifactName the optional name of an artifact (omit to perform operation on all environment artifacts) String false

Response

Returns application/json deployment operation reference

Example

Request POST http://kwatee.local:8080/kwate/api/deployments/intro/status
Response 202
{
  "ref" : "1:1417387427690"
}

GetOngoingOperation

GET /kwatee/api/deployments/ongoing.json

Retrieves an ongoing deployment operation.

Response

Returns application/json deployment operation reference

Example

Request GET http://kwatee.local:8080/kwate/api/deployments/ongoing.json
Response 200
{
  "ref" : "1:1417387427690"
}

hasOperationCompleted

GET /kwatee/api/deployments/progress/status

Is an ongoing operation in progress?

Parameters

Name Description Type Mandatory
RequestParam ref the reference of an ongoing deployment operation String false

Response

Example

Request GET http://kwatee.local:8080/kwate/api/deployments/progress/status
Response 200

GetOperationProgress

GET /kwatee/api/deployments/progress/status.json

Retrieves the progress of a deployment operation.

Parameters

Name Description Type Mandatory
RequestParam ref the reference of an ongoing deployment operation String false

Response

Returns application/json deployment operation progress

Example

Request GET http://kwatee.local:8080/kwate/api/deployments/progress/status.json?ref=1:1417387427690
Response 200
{
  "operation" : "deploy",
  "status" : "done",
  "servers" : [
    {
      "server" : "demoserver",
      "status" : "ok",
      "artifacts" : [
        {
          "artifact" : "demowebsite",
          "status" : "ok"
        }
      ]
    }
  ]
}

GetProgressMessages

GET /kwatee/api/deployments/progress/messages.json

Retrieves the details of a deployment operation for a given server and or artifact.

Parameters

Name Description Type Mandatory
RequestParam ref the reference of an ongoing deployment operation String false
RequestParam serverName the name of the server for which info is requested String false
RequestParam artifactName the optional name of an artifact for which info is requested (if omitted, only server-wide info is returned) String false

Response

Returns application/json deployment operation details object

Example

Request GET http://kwatee.local:8080/kwate/api/deployments/progress/messages.json?ref=1:1417387427690&serverName=demoserver
Response 200
{
  "messages" : "Establishing server connection...\nConnection established\nDeploy of artifact demowebsite[1.0] in intro-snapshot@demoserver\nDeploy complete"
}

ManageCancel

POST /kwatee/api/deployments/progress/cancel

Cancels an ongoing operation.

Parameters

Name Description Type Mandatory
RequestParam ref the reference of an ongoing deployment operation String false
RequestParam dontClear if true the status is kept active boolean false

Response

Example

Request POST http://kwatee.local:8080/kwate/api/deployments/progress/cancel?ref=1:1417387427690
Response 200

SendCredentials

POST /kwatee/api/deployments/progress/credentials

Supply server credentials without storing them in kwatee.

Parameters

Name Description Type Mandatory
RequestParam environmentName the name of an environment String false
RequestParam serverName the name of the server String false
RequestParam sameForAll optional, if true, these same credentials will be applied to all servers that need it. boolean false
RequestBody credentials the optional JSON credentials String true

Response

Example

Request POST http://kwatee.local:8080/kwate/api/deployments/progress/credentials?environmentName=intro&deploymentName=snapshot
{
  "credendials" : {
    "login" : "kwtest",
    "password" : "password"
  }
}
Response 200

GetInfoContext

GET /kwatee/api/info/context.json

Retrieves kwatee information.

Response

Returns application/json kwatee context object

Example

Request GET http://kwatee.local:8080/kwate/api/deployments/info/context.json
Response 200
{
  "organization" : "<your organisation name here>",
  "version" : "Version 4.0.2",
  "user" : "admin",
  "copyright" : "Copyright 2010-2015"
}

GetInfoPlatforms

GET /kwatee/api/info/platforms.json

Retrieves the available platforms.

Response

Returns application/json array of platform objects

Example

Request GET http://kwatee.local:8080/kwate/api/deployments/info/platforms.json
Response 200
[
  {
    "id" : 1,
    "name" : "linux_x86"
  },
  {
    "id" : 7,
    "name" : "linux_64"
  },
  {
    "id" : 3,
    "name" : "solaris_x86"
  },
  {
    "id" : 4,
    "name" : "solaris_sparc"
  },
  {
    "id" : 2,
    "name" : "macosx_x86"
  },
  {
    "id" : 8,
    "name" : "aix"
  },
  {
    "id" : 5,
    "name" : "win32"
  },
  {
    "id" : 9,
    "name" : "win64"
  }
]

GetInfoConduitTypes

GET /kwatee/api/info/conduitTypes.json

Retrieves the available conduit types.

Response

Returns application/json array of conduit type objects

Example

Request GET http://kwatee.local:8080/kwate/api/deployments/info/conduitTypes.json
Response 200
[
  {
    "id" : "telnetftp",
    "name" : "Telnet / FTP"
  },
  {
    "id" : "ssh",
    "name" : "Secure Shell / scp"
  }
]

GetInfoServerPoolTypes

GET /kwatee/api/info/serverPoolTypes.json

Retrieves the available server pool types.

Response

Returns application/json array of server pool type objects in case of success

Example

Request GET http://kwatee.local:8080/kwate/api/deployments/info/serverPoolTypes.json
Response 200
[
  {
    "id" : "manual",
    "name" : "Enumerated pool"
  },
  {
    "id" : "ec2",
    "name" : "Amazon EC2 pool"
  }
]