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: Register new servers Manage existing servers Manage server groups Restart servers Access and manage files on servers Create and manage deployments To use the API, you can use any HTTP client. All APIs use JSON as the data format.

Already familiar with the API? Jump straight to the operations: Operations for Servers Operations for Server Groups Operations for Deployments

If you are using Java we recommend the Jersey client or HttpClient with Jackson for JSON support.

Status Codes and Error Handling

When you call the REST APIs, the following status codes are returned:

When errors occur (e.g., a 500 status code), the HTTP response will contain a JSON response with an error message. For example:

500 
Content-Type: application/json
Server: Apache-Coyote/1.1
Date: Sun, 08 Nov 2009 00:12:55 GMT

{
  message : "Could not connect to remote server."
}

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:

{
  "id" : "1234567890",
  "href" : "http://localhost:8080/console/api/servers/1234567890",
  "name" : "DevelopmentServer1",
  "type" : "Apache Tomcat/6.0.20",
  "hosts" : [ "http://192.168.1.105:8090", "http://192.168.1.105:8010" ],
  "environmentVariables" : [
    { 
      "JAVA_OPTS : "-Xmx1024m -XX:MaxPermSize:1024m",
    }
  ],
  "groups" : [
    { 
      "name" : "Development",
      "href" : "http://localhost:8080/console/api/serverGroups/73d89173-290e-4cb3-a61c-e11deb74767d"
    }
  ],
  "deployments" : [
    { 
      "name" : "Test",
      "href" : "http://localhost:8080/console/api/deployments/local$fb9dcb67-88de-482a-b0a4-50ff1d65a16a"
    }
  ]
}

Server Properties

Following are the properties for servers.

Deployment Properties

Server Group Properties

Operations for Servers

Following is a summary of the operations you can perform on servers and the resource you specify for each.

All Servers

Individual Servers

Files

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:

{
  "name" : "renamed",
  "id" : "c4f7d8ce-21a7-4730-9447-37d8a7f8aab0",
  "serverCount" : 0,
  "href" : "http://localhost:8080/console/api/serverGroups/c4f7d8ce-21a7-4730-9447-37d8a7f8aab0"
}

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.

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

Individual Server Groups

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:

{
  "id" : "local$8ffe969e-77c1-497d-8d28-4a9bd56d886a",
  "name" : "Test",
  "action" : "DEPLOY",
  "lastModified" : 1257872258783,
  "status" : "In Process",
  "href" : "http://localhost:8080/console/api/deployments/local$8ffe969e-77c1-497d-8d28-4a9bd56d886a",
  "applications": [
    {
      "name" : "test.war",
      "href" : "http://localhost:8080/console/api/registry/Applications/test.war/1.0"
    }
  ],
  "servers": [
    { 
      "name" : "DevelopmentServer1 ",
      "href" : "http://localhost:8080/console/api/servers/local$c458777f-122f-4f7a-8451-6cccfdd6c94e" 
    }
  ]
}

Deployment Properties

Following are the properties for deployments.

Application Properties

Following are the properties for applications.

Server Properties

Following are the properties for servers.

Operations for Deployments

Following is a summary of the operations you can perform on deployments and the resource you specify for each.

All Deployments

Individual Deployment