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 packages 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 Packages

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"
    }
  ],
  "packages" : [
    { 
      "name" : "Test",
      "href" : "http://localhost:8080/console/api/packages/local$fb9dcb67-88de-482a-b0a4-50ff1d65a16a"
    }
  ]
}

Server Properties

Following are the properties for servers.

Package 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 Packages

The package API allows you to list and find packages, create packages, update packages, delete packages, and view package history. All resources/methods that return or accept a type, except where noted, use the package 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/packages/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" 
    }
  ]
}

Package Properties

Following are the properties for packages.

Application Properties

Following are the properties for applications.

Server Properties

Following are the properties for servers.

Operations for Packages

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

All Packages

Individual Package