Using the REST API
|
The REST API for Tcat Server provides a way for you to programmatically access much of Tcat's functionality. It allows you to:
To use the API, you can use any HTTP client. All APIs use JSON as the data format. |
|
Status Codes and Error Handling
When you call the REST APIs, the following status codes are returned:
Status Code |
Description |
|---|---|
200 |
The operation was successful. |
201 |
The resource (e.g., server, server group, deployment) was created. The Location header will contain the location of the resource. |
404 |
The resource was not found. |
409 |
When creating a resource (e.g., server, server group, deployment), a resource with that name already existed. |
500 |
The operation was unsuccessful. See the HTTP body for details. |
When errors occur (e.g., a 500 status code), the HTTP response will contain a JSON response with an error message. For example:
Working with Servers
The server API allows you to find, create, update, and delete servers. You can also perform operations related to managing a server such as restarting it or uploading files to it.
All resources/methods that return or accept a type, except where noted, use the server JSON type, which looks like this:
Server Properties
Following are the properties for servers.
Property |
Description |
|---|---|
id |
The unique ID of the server |
href |
The URL where the server is located |
type |
The type of server, e.g., "Apache Tomcat 6.0.20" |
hosts |
A list of the hosts on this server |
groups |
A list of the groups to which this server belongs |
name |
The name of the server |
deployments |
An array of the deployments that are deployed to this server. See below for a description of the properties. |
environmentVariables |
A map of environment variables which will be set on the server. |
Deployment Properties
name |
The name of the deployment |
href |
The URL where the deployment is located |
Server Group Properties
name |
The name of the server group |
href |
The URL where the server group is located |
Operations for Servers
Following is a summary of the operations you can perform on servers and the resource you specify for each.
All Servers
Operation |
Resource |
Description |
|---|---|---|
/console/api/servers |
Lists all servers on the resource |
Individual Servers
Operation |
Resource |
Description |
|---|---|---|
/console/api/servers/myServerId |
Gets a server |
|
/console/api/servers |
Registers a new server |
|
/console/api/servers/myServerId?profile=aProfileId |
Applies a profile to a server |
|
/console/api/servers/myServerId/restart |
Restarts a server |
|
/console/api/servers/myServerId |
Updates a server |
|
/console/api/servers/myServerId |
Deletes a server |
Files
Operation |
Resource |
Description |
|---|---|---|
/console/api/servers/myServerId/files/myFile.xml |
Gets a file located on the server |
|
/console/api/servers/myServerId/files/myFile.xml?metadata=true |
Gets the metadata for a file located on the server |
|
/console/api/servers/myServerId/files/myFile.xml |
Updates or creates a file or directory located on the server |
|
/console/api/servers/myServerId/files/myFile.xml |
Updates a file located on the server |
|
/console/api/servers/myServerId/files/myFile.xml |
Deletes a file located on the server |
Working with Server Groups
As with servers, you can perform operations on all server groups at once or on an individual server group. All resources/methods that return or accept a type, except where noted, use the server group JSON type. Here is an example:
Server Group Properties
Following are the properties for server groups. These properties appear when you retrieve a server group, and you specify the name property when taking actions like creating a new server group.
Property |
Description |
|---|---|
name |
The name of the group |
id |
The unique ID of the group |
href |
The URL where the server group is located |
serverCount |
The number of servers currently in this group |
Operations for Server Groups
Following is a summary of the operations you can perform on one or all server groups and the resource you specify for each.
All Server Groups
Operation |
Resource |
Description |
|---|---|---|
/console/api/serverGroups |
Lists all server groups on the resource |
Individual Server Groups
Operation |
Resource |
Description |
|---|---|---|
/console/api/serverGroups |
Creates a new server group |
|
/console/api/serverGroups/serverGroupId |
Gets a server group |
|
/console/api/serverGroups/serverGroupId?profile=aProfileId |
Applies a profile to a server group |
|
/console/api/serverGroups/serverGroupId |
Updates a server group |
|
/console/api/serverGroups/serverGroupId |
Deletes a server group |
Working with Deployments
The deployment API allows you to list and find deployments, create deployments, update deployments, delete deployments, and view deployment history. All resources/methods that return or accept a type, except where noted, use the deployment JSON type, which looks like this:
Deployment Properties
Following are the properties for deployments.
Property |
Description |
|---|---|
id |
The unique ID of the deployment |
name |
The name of the deployment |
action |
The last action taken on the deployment, one of: DEPLOY, REDEPLOY, UNDEPLOY, or DELETE |
lastModified |
The date the deployment was last changed |
status |
The status of the last action taken |
href |
The URL of the deployment |
applications |
An array of applications |
servers |
An array of server references |
Application Properties
Following are the properties for applications.
Property |
Description |
|---|---|
contextPath |
The context path where the application is deployed or will be deployed. |
href |
The URL of the application inside the repository. See the Repository API for more details. |
name |
The name of the application. |
Server Properties
Following are the properties for servers.
Property |
Description |
|---|---|
href |
The URL of the server. See the description of |
name |
The name of the server. |
Operations for Deployments
Following is a summary of the operations you can perform on deployments and the resource you specify for each.
All Deployments
Operation |
Resource |
Description |
|---|---|---|
/console/api/deployments |
Gets a list of all deployments on the resource. |
Individual Deployment
Operation |
Resource |
Description |
|---|---|---|
/console/api/deployments |
Creates a new deployment |
|
/console/api/deployments/deploymentId |
Gets a deployment |
|
/console/api/deployments/deploymentId |
Updates a deployment |
|
/console/api/deployments/deploymentId/history |
Gets the history for a deployment |
|
/console/api/deployments/deploymentId/deploymentVersionId |
Gets the details about a particular version of a deployment |
|
/console/api/deployments/deploymentId/redeploy |
Redeploys a deployment |
|
/console/api/deployments/deploymentId/undeploy |
Undeploys a deployment |
|
/console/api/deployments/deploymentId |
Deletes a deployment |
This page
Other pages
Account
Administration