Contact Us 1-800-596-4880
  1. Homepage
  2. Tcat Server (7.1)

  3. Using the REST API

Using the REST API

Tcat Server reached its End of Life in 2017. Contact your Customer Success Manager to determine options for managing, monitoring, or deploying your application.

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:

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

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 (for example, server, server group, deployment) was created. The Location header contains the location of the resource.

404

The resource was not found.

409

When creating a resource (for example, 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 (for example, a 500 status code), the HTTP response contains a JSON response with an error message. For example:

500
Content-Type: application/json
Server: Apache-Coyote/1.1
Date: Mon, 10 Aug 2015 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.

Property Description

id

The unique ID of the server

href

The URL where the server is located

type

The type of server, for example, "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 are 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

GET

/console/api/servers

Lists all servers on the resource

Individual Servers

Operation Resource Description

GET

/console/api/servers/myServerId

Gets a server

POST

/console/api/servers

Registers a new server

POST

/console/api/servers/myServerId?profile=aProfileId

Applies a profile to a server

POST

/console/api/servers/myServerId/restart

Restarts a server

PUT

/console/api/servers/myServerId

Updates a server

DELETE

/console/api/servers/myServerId

Deletes a server

Files

Operation Resource Description

GET

/console/api/servers/myServerId/files/myFile.xml

Gets a file located on the server

GET

/console/api/servers/myServerId/files/myFile.xml?metadata=true

Gets the metadata for a file located on the server

POST

/console/api/servers/myServerId/files/myFile.xml

Updates or creates a file or directory located on the server

PUT

/console/api/servers/myServerId/files/myFile.xml

Updates a file located on the server

DELETE

/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:

{
  "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.

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

GET

/console/api/serverGroups

Lists all server groups on the resource

Individual Server Groups

Operation Resource Description

POST

/console/api/serverGroups

Creates a new server group

GET

/console/api/serverGroups/serverGroupId

Gets a server group

POST

/console/api/serverGroups/serverGroupId?profile=aProfileId

Applies a profile to a server group

PUT

/console/api/serverGroups/serverGroupId

Updates a server group

DELETE

/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:

{
  "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.

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 href in Server Properties above.

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

GET

/console/api/deployments

Gets a list of all deployments on the resource.

Individual Deployment

Operation Resource Description

POST

/console/api/deployments

Creates a new deployment

GET

/console/api/deployments/deploymentId

Gets a deployment

PUT

/console/api/deployments/deploymentId

Updates a deployment

GET

/console/api/deployments/deploymentId/history

Gets the history for a deployment

GET

/console/api/deployments/deploymentId/deploymentVersionId

Gets the details about a particular version of a deployment

POST

/console/api/deployments/deploymentId/redeploy

Redeploys a deployment

POST

/console/api/deployments/deploymentId/undeploy

Undeploys a deployment

DELETE

/console/api/deployments/deploymentId

Deletes a deployment