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