Examples of URIs

Edit online

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

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

DELETE

Edit online

Clears a cache, or clears cache statistics.

The following DELETE examples are organized by task and URI.

Clear a Cache

/agents;id=client01/cacheManagers;names=foo/caches;names=bar/elements

Removes the elements from the cache "bar" of 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

Edit online

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.

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.

With the v2 REST API, /v2/agents/info returns a response with additional information, for example: 

{"agentId":"TMS","apiVersion":"v2","entities":[{"agentId":"MyCluster",
"productVersion":"4.3.0","agencyOf":"TSA",
"available":true,"secured":true,"sslEnabled":true,"needClientAuth":false,
"licensed":true,"sampleHistorySize":670,
"sampleIntervalSeconds":4,"enabled":true},
{"agentId":"MyCluster$localhost_50808","productVersion":"2.10.0",
"agencyOf":"Ehcache","available":true,"secured":true,"sslEnabled":true,
"needClientAuth":false,"licensed":true,"sampleHistorySize":30,
"sampleIntervalSeconds":1,"enabled":true}],
"exceptionEntities":[{"agentId":"MyCluster-1",
"message":"javax.ws.rs.ProcessingException:
 java.net.SocketTimeoutException: connect timed out","stackTrace":
"java.util.concurrent.ExecutionException: javax.ws.rs.ProcessingException:
 java.net.SocketTimeoutException: connect timed out\n\tat...

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"/> 
        <elementValueComparatorclass= 
"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 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, an error is returned in the JSON response. The JVM argument com.terracotta.agent.defaultMaxClientsToDisplay can be used to change the maximum number of clients to display.

With the v2 REST API, /v2/agents/cacheManagers returns a response such as: 

{"agentId":"TMS","apiVersion":"v2","entities":[ 
{"agentId":"MyCluster$localhost_50808","name":"MyCluster-1","attributes": 
{"ClusterUUID":"b769bf9f44c54242a5d6eff8b1ad9dc3","Enabled":true, 
"HasWriteBehindWriter":false,"MaxBytesLocalDiskAsString":"0","Searchable":true," 
MaxBytesLocalDisk":0,"CacheNames":["bigMemorySample"], 
"MaxBytesLocalOffHeapAsString":"4G","Status":"STATUS_ALIVE", 
"MaxBytesLocalOffHeap":4000000000,"WriterMaxQueueSize":0, 
"MaxBytesLocalHeapAsString":"1G","Transactional":false,"MaxBytesLocalHeap" 
:1000000000}}],"exceptionEntities":[{"agentId":"MyCluster-1","message" 
:"javax.ws.rs.ProcessingException: java.net.SocketTimeoutException: 
connect timed out","stackTrace":...

Get Offline Data

The TMS Rest API allows you to request offline cache managers and offline cache information (and even the possibility to destroy offline cache managers and caches).

The various REST endpoints available for offline data are described here:

REST endpoint: 
GET  /agents/clusters/cacheManagers

Use this to list all offline and online CacheManagers from all known agents (use ;ids on agents to filter agents, and ;names to filter cacheManagers).

Sample output: 

[
  {
    version: "4.3.0.0.26",
    name: "__DEFAULT__",
    agentId: "MyCluster",
    attributes: {
      inUse: "true"
    }
  }
]

In this example, the cacheManager named __DEFAULT__ is still in use, meaning at least one client is using it, and therefore you can't delete it.

REST endpoint: 
GET  /agents/clusters/cacheManagers/configs

Use this to list cache manager configurations.

Sample output: 

[
  {
    version: "4.3.0.0.26",
    cacheManagerName: "__DEFAULT__",
    agentId: "MyCluster",
    xml: "<ehcache name="__DEFAULT__" updateCheck="false"> 
            <diskStore path="java.io.tmpdir"/> 
            <defaultCache maxEntriesLocalHeap="0"/> 
            <terracottaConfig url="tsa:9510"/> 
          </ehcache> "
  }
]
REST endpoint: 
GET  /agents/clusters/cacheManagers/caches

Use this to list caches (you can also use ;names on /caches to filter caches).

Sample output: 

[
  {
    version: "4.3.0.0.26",
    agentId: "MyCluster",
    name: "vets",
    cacheManagerName: "__DEFAULT__",
    attributes: {
      inUse: "true"
    }
  }
]

In this example, we can see that the cache named "vets" from the Cache Manager __DEFAULT__ is in use, and thus cannot be destroyed.

REST endpoint: 
GET  /agents/clusters/cacheManagers/caches/configs

Use this to list cache configurations.

Sample output: 

[
  {
    version: "4.3.0.0.26",
    cacheName: "vets",
    cacheManagerName: "__DEFAULT__",
    agentId: "MyCluster",
      xml: "<cache name="vets" maxEntriesLocalHeap="100" 
              diskExpiryThreadIntervalSeconds="1" timeToLiveSeconds="60" 
              maxEntriesInCache="10000000"> 
              <terracotta> <nonstop enabled="false"/> </terracotta> 
            </cache> "
    }
]
REST endpoint: 
DELETE /agents;ids=MyCluster/clusters/cacheManagers;names=__DEFAULT__/caches;names=vets

Use this to delete a cache. Note the mandatory use of all the filters ids, and names; this is because you need to be very precise when deleting a cache. As for all non GET operations on the TMS, you need to include CSRF tokens in the HTTP headers : 

OWASP_CSRFTOKEN:XXXX (you need to get this from your last GET request)
X-Requested-With:OWASP CSRFGuard Project

{
error: "Failed to destroy the cache vets"
details: "Unable to lock cache vets for destruction"
stackTrace: null
}

In this example, you can see that we tried to delete a cache that was still in use.

If you try again after the cache is no longer in use (inUse:false) then you will receive an empty HTTP response, with the 204 status, indicating that your cache was deleted successfully.

REST endpoint: 
DELETE /agents;ids=MyCluster/clusters/cacheManagers;names=__DEFAULT__

Use this to delete a cache. Note the mandatory use of all the filters ids, and names; this is because you need to be very precise when deleting a cache manager. As for all non GET operations on the TMS, you need to include CSRF tokens in the HTTP headers : 

OWASP_CSRFTOKEN:XXXX (you need to get it from your last GET request)
X-Requested-With:OWASP CSRFGuard Project

{
error: "Failed to destroy the cacheManager __DEFAULT__"
details: "Unable to lock entity __DEFAULT__ of type interface com.terracotta.entity.ehcache.ClusteredCacheManager for destruction"
stackTrace: null
}

In this example, you can see that we tried to delete a cache manager that was still in use.

If you try again after the cache manager is no longer in use (inUse:false) then you will receive an empty HTTP response, with the 204 status. Your cache manager was deleted successfully.

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

Edit online

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

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="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

Edit online

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.

Updating a Cache Attribute

The following URI can update the cache attributes as specified in the content. 

/agents;ids=MyConnectionGroup_MyEhcache/cacheManagers;names=foo/caches;names=baz

For example, to turn off statistics gathering for the cache "baz", you would use the following content: 

{"attributes":{"StatisticsEnabled":false}}
The attributes you can modify in this way are described in Allowed Resource Updates.

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.