Call us: +1-415-738-4000

Terracotta REST API

Introduction

The Terracotta Management Server (TMS) includes an embedded management REST interface. You can write custom scripts against this interface, or create a custom Rich Internet Application in place of the Terracotta Management Console (TMC).

This document defines and describes the management REST API used to interact with the REST interface agent.

NOTE: For simplicity, many of the examples given in this document assume a TMS that is running locally, and therefore "localhost" is used for the host address.

Connecting to the Management Service REST API

The REST API is available by connecting to the REST management service running on the TMS or a node running a REST agent. Use the URLs shown below.

Connecting to a TMS

http://<host>:<port>/tmc/api

where <port> is 9889 if running the TMS with the default container. If using your own container, substitute the port configured for that container.

Connecting Directly to a Standalone Node

http://<host>:<port>/tc-management-api

where <port> is configured in the <managementRESTService> element's bind attribute, in the Ehcache configuration file (ehcache.xml by default).

Connecting to a TSA

http://<host>:<port>/tc-management-api

where <port> is the TSA group port. This value is configured in a server's <tsa-group-port> element in the Terracotta configuration file (tc-config.xml by default). The default value for the group port is 9530.

Constructing URIs for HTTP Operations

The typical URI used to connect to the Terracotta management service has the following format:

<scheme>://<host>[:<port>]/<path>?<query>

These URIs use the standard scheme and domain, with "http" assumed as the scheme. HTTP operations access the REST API through URIs. The URI allows query strings under certain circumstances.

The URI Path

The <path> portion of the URI specifies resource locations using the following hierarchy:

  1. Agent IDs – List of the desired clients using unique identifiers. If the connection is to a TMS and no IDs are given, all known clients are accessed. If the connection is made directly to a Terracotta client or the TSA (to a standalone REST service), then no ID is used since these are identified by a host:port address. All standalone (including TSA) REST interfaces will return the agent ID "embedded".

  2. CacheManager names – List of the CacheManagers using their configured names. If "cacheManagers" is specified in the URI but no names are given, all CacheManagers for the specified clients are accessed.

  3. Cache names – List of the caches using their configured names. If "caches" is specified in the URI but no names are given, all caches belonging to the accessed CacheManagers are accessed. In the case where access is broad, a substantial amount of data may be returned by a GET operation.

The structure of the path takes the following form:

/agents[;ids={comma_sep_agent_ids}]/cacheManagers[;names={comma_sep_cache_manager_names}]
    /caches[;names={comma_sep_cache_names}

Agent IDs are not required.

Special Resource Locations

Certain resource locations provide specific monitoring and administration services.

Discovery

A "discovery" URI format uses the path /agents/info. Used with a TMS, this URI returns metadata on all agents known (through configuration) to that TMS. Used with an embedded web service, metadata on that agent is returned (or a 404 if that agent is not reachable). Examples of other specific uses of discovery URIs are given elsewhere in this document.

Viewing Configuration

A URI format for viewing the configuration of CacheManagers and caches uses the path agents/cacheManagers or agents/cacheManagers/caches. Agents, cacheManagers, and caches can be specified using IDs and names. The data is returned in its native XML format.

To get the configuration of one or more CacheManagers, use the following format:

/agents[;ids={comma_sep_agent_ids}]/cacheManagers[;names={comma_sep_cache_manager_names}]
    /configs

Note: If no client IDs are specified in the request, then all of the clients' cacheManagers are returned. However, if no client IDs are specified in the request and the number of clients is more than the default maximum of 64, then an error is returned in the JSON response. The VM argument com.terracotta.agent.defaultMaxClientsToDisplay can be used to change the maximum number of clients to display.

To get the configuration of one or more caches, use the following format:

/agents[;ids={comma_sep_agent_ids}]/cacheManagers[;names={comma_sep_cache_manager_names}]
     /caches[;names={comma_sep_cache_names}/configs

Setting Configuration

Cache resource locations can also be specified for setting specific cache-configuration attributes using resource representations. The following is a comprehensive list of the attributes that can be set:

  • enabled – A boolean for enabling (true, DEFAULT) or disabling (false) cache operations. For example, to disable a cache's operation: PUT {"enabled":true}.

  • statsEnabled – A boolean for enabling (true) or disabling (false, DEFAULT) the gathering of cache statistics.

  • sampledStatsEnabled – A boolean for enabling (true) or disabling (false, DEFAULT) the sampling of cache statistics.

Probing a New Connection URI

To probe the existence of an agent at a given location, use an URL with the following format:

    http://127.0.0.1:9889/tmc/api/agents/probeUrl/$urlToProbe

For example, the following should return information about the REST agent running at the given address (localhost:4343):

http://127.0.0.1:9889/tmc/api/agents/probeUrl/http%253A%252F%252Flocalhost%253A4343

If the agent is available, a (status code 200 AgentMetadataEntity) response similar to the following is returned:

    {"agentId":"embedded","agencyOf":"Ehcache","available":true,"secured":false,
"sslEnabled":false,"needClientAuth":false,"licensed":false,"sampleHistorySize":8640,
"sampleIntervalSeconds":10,"enabled":false,"restAPIVersion":"2.7.0"}

If not available, the status code should be "204 No Content".

Setting the authentication mode

The authentication status is saved in the properties file ${user.home}/.tc/mgmt/settings.ini. There is a REST resource to interact with it (setting it on and off); setting it forces a manual restart of the TMS.

To GET the status, use the following URI:

http://localhost:9889/tmc/api/config/settings/authentication

Either "true" or "false" is returned.

To change (PUT) the status, call the same url with a request body containing "true" or "false". A "200 OK" status code is returned upon successful update.

See the examples of URIs, below, for how to use these resource locations.

Specifications for HTTP Operations

If no agent IDs are specified in a URI, all known agents are included.

Response Headers

For a typical HTTP request, the response header appears similar to the following:

   -- response --
200 OK
Content-Type:  application/vnd.sun.wadl+xml
Allow:  OPTIONS,GET,HEAD
Content-Length:  602
Server:  Jetty(7.5.4.v20111024)

Examples of URIs

The flexibility of the management-service REST API in turn makes available a flexible URI syntax. The following list of examples illustrate HTTP responses to specific URIs. These examples of the data returned by the listed HTTP operations are shown below without response headers.

DELETE

Removes a specified resource, such as a cache.

Examples

The following DELETE examples are organized by task and URI.

Remove a Cache
/agents;id=client01/cacheManagers;names=foo/caches;names=bar

Remove the cache "bar" from CacheManager "foo" on the Ehcache node "client01".

Clear Cache Statistics
/agents;id=client01/cacheManagers;names=foo/caches;names=bar/configs

Clears all cache statistics for cache "foo" and resets counters to zero.

Possible HTTP Status Codes for DELETE

400 – URI does not specify a single resource. 404 – Resource specified in the URI cannot be found.

GET and HEAD

Returns a JSON array representing the details of all specified resources, or an XML representation of data whose native format is XML.

NOTE: HEAD operations return the same metadata as GET operations, but no body.

Examples

The following GET examples are organized by task and URI.

Discover All Known Agents
/agents/info

Used with a TMS, this URI returns metadata on all agents known (through configuration) to that TMS. Used with an embedded web service, metadata on that agent is returned.

The following is a response from a TMS that has agents "foo" and "goo" configured, and both are responding:

[{"restAPIVersion":"1.0.0","available":true,"agentId":"foo","agencyOf":"Ehcache"}, 
{"restAPIVersion":"1.0.0","available":true,"agentId":"goo","agencyOf":"Ehcache"}]

The following is a response from a TMS that has agents "foo" and "goo" configured, but with only "foo" responding:

[{"restAPIVersion":"1.0.0","available":true,"agentId":"foo","agencyOf":"Ehcache"}, 
{"restAPIVersion":null,"available":false,"agentId":"goo","agencyOf":null}]

Note that the metadata returned includes the API version running on the agent, as well as the type of client ("agencyOf") the API is serving.

Get Details on Specific Agents
/agents;ids=client01,client02

JSON representing an array all available agent detail. If no agent IDs are included, all agents available are returned.

Get Details on Specific Caches
/agents;ids=client01/cacheManagers;names=foo/caches;names=bar
Get Configuration of Specific CacheManager
/agents;ids=client01/cacheManagers;names=foo/configs

Returns an XML representation of the CacheManager "foo". For example, the following is an XML representation returned from a standalone Ehcache node:

<configurations agentId="embedded" version="1.0.0-SNAPSHOT">
  <configuration cacheManagerName="foo">
    <ehcache maxBytesLocalDisk="300M" maxBytesLocalHeap="100M" maxBytesLocalOffHeap="200M" 
    monitoring="on" name="CM1">
    <diskStore path="/var/folders/nn/lxsg77756534qfn7z14y5gtm0000gp/T/"/>
      <managementRESTService bind="0.0.0.0:9889" enabled="false"/>
      <cache name="Cache11">
    <persistence strategy="localTempSwap"/>
        <elementValueComparator class="net.sf.ehcache.store.DefaultElementValueComparator"/>
        <terracotta clustered="false">
          <nonstop/>
        </terracotta>
      </cache>
    </ehcache>
  </configuration>
</configurations>

Certain operations can only be executed against specific targets. Specifying multiple agents, CacheManagers, or caches will generate an error response (code 400).

Get Configuration of Specific Caches
/agents;ids=client01/cacheManagers;names=foo/caches;names=baz/configs
Get All CacheManager Details
/agents/cacheManagers

The following example shows a JSON object returned by this URI when the GET is executed against a standalone Ehcache node with two CacheManagers, each with one cache:

    [{"name":"CM2","attributes":{"ClusterUUID":"03e505092b6a4b1a9af5d1b035a7d5ed","
Enabled":true,"HasWriteBehindWriter":false,"MaxBytesLocalDiskAsString":"300M","
CacheAverageSearchTime":0,"CachePutRate":84,"CacheOnDiskHitRate":0,
"CacheMetrics":{"Cache12":[2,84,84]},
"CacheRemoveRate":0,"CacheOffHeapHitRate":0,"Searchable"
:false,"CacheOnDiskMissRate":84,"CacheNames":["Cache12"],"
TransactionRolledBackCount":0,"CacheInMemoryHitRate":2,"WriterQueueLength":0,"
CacheOffHeapMissRate":0,"Transactional":false,"CacheHitRate":2,"
TransactionCommitRate":0,"CacheExpirationRate":0,"CacheUpdateRate":0,"
MaxBytesLocalHeap":104857600,"CacheAverageGetTime":0.027891714,"
TransactionRollbackRate":0,"CacheEvictionRate":0,"CacheInMemoryMissRate":84,"
MaxBytesLocalDisk":314572800,"MaxBytesLocalOffHeapAsString":"200M","
CacheSearchRate":0,"TransactionCommittedCount":0,"TransactionTimedOutCount":0,"
Status":"STATUS_ALIVE","MaxBytesLocalOffHeap":209715200,"WriterMaxQueueSize":0,"
StatisticsEnabled":true,"MaxBytesLocalHeapAsString":"100M","CacheMissRate":84},"
agentId":"embedded","version":"1.0.0-SNAPSHOT"},{"name":"CM1","attributes":
{"ClusterUUID":"03e505092b6a4b1a9af5d1b035a7d5ed","Enabled":true,"
HasWriteBehindWriter":false,"MaxBytesLocalDiskAsString":"300M","
CacheAverageSearchTime":0,"CachePutRate":166,"CacheOnDiskHitRate":8,"
CacheMetrics":{"Cache11":[7,83,83],"Cache12":[6,83,83]},"CacheRemoveRate":0,"
CacheOffHeapHitRate":0,"Searchable":false,"CacheOnDiskMissRate":166,"CacheNames"
:["Cache11","Cache12"],"TransactionRolledBackCount":0,"CacheInMemoryHitRate":5,"
WriterQueueLength":0,"CacheOffHeapMissRate":0,"Transactional":false,"
CacheHitRate":13,"TransactionCommitRate":0,"CacheExpirationRate":0,"
CacheUpdateRate":0,"MaxBytesLocalHeap":104857600,"CacheAverageGetTime":0.061820637,
"TransactionRollbackRate":0,"CacheEvictionRate":0,"CacheInMemoryMissRate":174,"
MaxBytesLocalDisk":314572800,"MaxBytesLocalOffHeapAsString":"200M","
CacheSearchRate":0,"TransactionCommittedCount":0,"TransactionTimedOutCount":0,"
Status":"STATUS_ALIVE","MaxBytesLocalOffHeap":209715200,"WriterMaxQueueSize":0,"
StatisticsEnabled":true,"MaxBytesLocalHeapAsString":"100M","CacheMissRate":166},
"agentId":"embedded","version":"1.0.0-SNAPSHOT"}]

Note: When no client IDs are specified in the request, all of the clients' cacheManagers are returned. However, if the number of clients is more than the default maximum of 64, then an error is returned in the JSON response. The VM argument com.terracotta.agent.defaultMaxClientsToDisplay can be used to change the maximum number of clients to display.

Get Specific CacheManager Details
/agents/cacheManagers?show=CacheInMemoryHitRate&show=CacheHitRate&show=CacheAverageGetTime

This URI returns a JSON array with only the specified statistics:

[{"name":"CM1","attributes":{"CacheAverageGetTime":0.26357448,"CacheHitRate":47,
"CacheInMemoryHitRate":3},"agentId":"embedded","version":"1.0.0-SNAPSHOT"}]

Configuration attributes (for example, MaxBytesLocalHeap) can also be specified with the show query parameter.

Possible HTTP Status Codes for GET or HEAD

404 – Specified resource is not found.

OPTIONS

Retrieves the WADL describing all of the operations available on the specified resources.

Examples

The following OPTIONS examples are organized by task and URI. Examples executed against standalone nodes show a base URI ending in "/tc-management-api/", while those executed against a TMS have a base URI ending in "/tmc/api/".

Return WADL With Available Agent Operations
/agents;ids=client01,client02

The following is an example of a WADL returned by an embedded agent:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://wadl.dev.java.net/2009/02">
<doc xmlns:jersey="http://jersey.java.net/"
    jersey:generatedBy="Jersey: 1.9.1
    09/14/2011 02:05 PM"/>
<grammars/>
<resources base="http://localhost:9888/tc-management-api/">
    <resource path="agents">
        <method name="GET" id="getAgents">
            <response>
                <representation mediaType="application/json"/>
            </response>
        </method>
        <resource path="/info">
            <method name="GET" id="getAgentsMetadata">
                <response>
                    <representation mediaType="application/json"/>
                </response>
            </method>
        </resource>
    </resource>
</resources>
</application>
Return WADL With Available CacheManager "Config" Operations
/agents/cacheManagers/configs

OPTIONS using /configs:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://wadl.dev.java.net/2009/02">
<doc xmlns:jersey="http://jersey.java.net/" 
    jersey:generatedBy="Jersey: 1.9.1 09/14/2011 02:05 PM"/>
<grammars/>
<resources base="http://localhost:9888/tc-management-api/">
  <resource path="agents/cacheManagers/configs">
      <method name="GET" id="getCacheManagerConfig">
        <response>
          <representation mediaType="application/xml"/>
        </response>
      </method>
    </resource>
  </resources>
</application>
Return a WADL With Available Operations on a Specific Cache
/agents/cacheManagers;names=foo,goo/caches;names=bar

Returns information on the cache "bar" from all CacheManagers "foo" and "goo" on any agent reachable by the TMS:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://wadl.dev.java.net/2009/02">
  <doc xmlns:jersey="http://jersey.java.net/" 
      jersey:generatedBy="Jersey: 1.9.1 09/14/2011 02:05 PM"/>
  <grammars/>
  <resources base="http://localhost:9889/api/">
    <resource path="agents/cacheManagers;names=foo,goo/caches;names=bar">
      <method name="GET" id="getCaches">
        <response>
          <representation mediaType="application/json"/>
        </response>
      </method>
      <method name="PUT" id="createCache"/>
      <method name="DELETE" id="deleteCache"/>
      <resource path="/statistics">
        <method name="DELETE" id="wipeStatistics"/>
      </resource>
    </resource>
  </resources>
</application>

For information from specific agents, specify the agent ID:

/agents;ids=client01,client02/CacheManagers=foo,bar/caches=baz,goo

Returns a WADL, as shown above, but with more detailed resource locations (and more caches).

Used with an embedded web service, this URI returns information for the specified caches found on that agent only.

PUT

Creates the specified resource or updates a resource representation.

Allowed Resource Updates

Updating a resource representation means editing the value of one of the following boolean cache attributes:

  • Enabled – Enable (true, DEFAULT) or disable (false) the cache.
  • StatisticsEnabled – Enable (true, DEFAULT) or disable (false) statistics gathering for the cache. Disabling statistics can improve a cache's performance, but limits monitoring capabilities. Note that if statistics are disabled, then sampled statistics are automatically disabled.

  • SampledStatiscsEnabled – Enable (true, DEFAULT) or disable (false) sampled statistics. Sampled statistics are used for providing averages and other aggregate values. If sampled statistics are enabled, statistics gathering is automatically enabled.

Examples

Create a New Cache
/agents;ids=MyConnectionGroup_MyEhcache/cacheManagers;names=foo/caches;names=baz

This URI creates the cache "baz" under the CacheManager "foo" on the Ehcache node with agent ID "MyConnectionGroup_MyEhcache". baz has the defaultCache configuration.

Update a Cache Attribute
/agents;ids=MyConnectionGroup_MyEhcache/cacheManagers;names=foo/caches;names=baz

This URI can update the cache attributes as specified in the content. For example, to turn off statistics gathering for the cache "baz", use the following content:

{"attributes":{"StatisticsEnabled":false}}

See Allowed Resource Updates for more information on updating cache configuration.

Possible HTTP Status Codes for PUT

201 – The operation was successful. 204 – The cache was successfully updated. 400 – The URI does not specify a single resource. 409 – The resource with the given name already exists.

Using Query Parameters in URIs

GET and HEAD HTTP operations can execute queries on specific resources. Query parameters are executed using the show parameter:

/agents[;ids={comma_sep_agent_ids}]/cacheManagers[;names={comma_sep_cache_manager_names}]
    /caches[;names={comma_sep_cache_names}?show=[parameter]&show=[parameter]

For example, to retrieve the values for the parameters HasWriteBehindWriter and MaxBytesLocalDiskAsString for the CacheManager CM1 on an Ehcache with the ID "foo", use the following:

/agents;ids=foo/cachemanagers;names=CM1?show=HasWriteBehindWriter?
    show=MaxBytesLocalDiskAsString

This query returns a JSON object similar to the following:

[{"name":  "CM1","attributes":  {"HasWriteBehindWriter":true,
    "MaxBytesLocalDiskAsString":"300M"},"guid":"95d40b093c9f44389f3cc122fbe1c30b",
"agentId":"embedded","version":"1.0.0"}]

API Version

All REST APIs should have the same version to avoid potential issues due to differing features and capabilities (see the section on version mismatches. Note that the REST API version is unrelated to the version of Terracotta products or any other Terracotta APIs.

You can discover the API version of connected REST agents using a GET operation with an /agents/info URI.

Version Mismatches

Differences in REST API versions can affect the features and functionality offered by the monitoring tools you create. Over time, version mismatches can arise between the TMS and TSA (when using an external TMS), and between the TMS and standalone nodes.

The TMS may be able to compensate agents with API versions older than its own version by exposing only their available capilities. Newer agent API versions can cause inconsistent behavior or malfunction if the TMS is unable to handle unfamiliar schema, functionality, or other differences in APIs.

JSON Schema

Use the schema as a guide to parsing the JSON objects returned by the REST API, and to validate the structure of data your scripts or RIA sends to agents.

Note that the schema is subject to change between API versions. You can use the REST API URIs to get examples of the JSON schema for the following:

  • cacheManager

  • cache

  • cacheConfig

  • cacheStatisticsSample

REST API for TSA

You can use the REST API to query the TMS regarding any connected TSA.

Statistics

Use the following URI extensions with the base extension /agents/statistics to return statistical information.

DGC Runs

Get statistics on the last 1000 DGC runs:

/dgc

Server Statistics

Get statistics k, l, and m for servers a, b, c:

/servers;names=a,b,c?show=k,l,m 

If no "names" are specified, statistics for all servers are requested. If "show" is omitted, all statistics are requested.

Client Statistics

Get statistics k, l, and m for clients x, y, and z:

/clients;ids=x,y,z?show=k,l,m

If no "ids" are specified, statistics for all clients are requested. If "show" is omitted, all statistics are requested.

Topology Views

Use the following URI extensions with the base extension /agents/topologies to return topological information.

To get a complete cluster topology (all servers and clients), end the base extension with a forward slash ("/"):

/agents/topologies/

To get only servers a, b, and c:

/servers;names=a,b,c 

If no "names" are specified, all servers are included.

To get only clients x, y, and z:

/clients;ids=x,y,z 

If no "ids" are specified, all clients are included.

Configuration

Use the following URI extensions with the base extension /agents/configurations to return configuration information.

To get the configuration settings for all servers and clients, end the base extension with a forward slash ("/"):

/agents/configurations/

To get only servers a, b, and c:

/servers;names=a,b,c

If no "names" are specified, all servers are included.

To get only clients x, y, and z:

/clients;ids=x,y,z

If no "ids" are specified, all servers are included.

Diagnostics

Use the following URI extensions with the base extension /agents/disagnostics to return information useful in diagnosing trouble or initiate a DGC cycle.

Thread Dumps

Get a full thread dump from all servers and clients:

/threadDump

Get a thread dump from servers a, b, and c:

/threadDump/servers;names=a,b,c

If no "names" are specified, all servers are included.

Get a thread dump from clients x, y, and z:

/threadDump/clients;ids=x,y,z

If no "ids" are specified, all clients are included.

Thread dumps are written to the logs of their respective nodes. To have all generated thread dumps saved to a zip file, use threadDumpArchive instead of threadDump.

To write cluster state information (including, for example, on locks) in addition to thread dumps for each node, use dumpClusterState instead of threadDump. This action generates substantially more information than getting only thread dumps.

DGC Cycles

To initiate a DGC cycle, post:

/dgc

Backups

You can initiate backups of the cluster data by posting with the following URI extension:

/agents/backups/

To get the status of a backup ("true" for a backup in progress), use a GET operation with the same URI extension:

/agents/backups/

Note that backup operations involve the entire TSA and cannot be delegated to specific servers.

Operator Events

You can return operator events using the URI extension /agents/operatorEvents. To limit the size of the returned data, use a sinceWhen query.

To get operator events for the last ten minutes:

/agents/operatorEvents?sinceWhen=10m

To limit events to certain types, add eventTypes:

/agents/operatorEvents?eventTypes=ERROR,WARN

These parameters can be combined:

/agents/operatorEvents?sinceWhen=10m&eventTypes=ERROR,WARN

Logs

You can return logs using the URI extension /agents/logs. To limit the size of the returned data, use a sinceWhen query.

To get logs for the last ten minutes:

/agents/logs?sinceWhen=10m