REST Cache Control

Caches Query and Control REST API

Stashed supports RESTful control of the caches. This is useful for using tools like CURL with build scripts to clear local caches, query cache capabilities on a host or configure the perecntage of local storage space avaialble for use as a build cache.

RESTful pattern of use

The API endpoint to access query and control for caches is located at /api/caches.

curl -s -X <operation> -k <url>

All mutating operations return an empty json object. The GET operation returns a list of caches on the host.

Examples

Querying all caches on the host system:

curl -s -X GET http://127.0.0.1:39081/api/caches

returns something like:

{
	"caches": [
		{
			"name": "memory",
			"limit": "10",
			"cacheSize": "1705136537",
			"deviceSize": "17051365376"
		},
		{
			"name": "disks/c",
			"path": "C:\\.stashed\\main",
			"entries": "242",
			"used": "7056436",
			"limit": "10",
			"cacheSize": "23990738124",
			"deviceSize": "239907381248"
		},
		{
			"name": "disks/d",
			"path": "D:\\.stashed\\main",
			"entries": "250",
			"used": "69377957",
			"limit": "10",
			"cacheSize": "100020203929",
			"deviceSize": "1000202039296"
		}
	]
}

depending on how many physical disks are on the system and how much memory is available.

Clear all caches

curl -s -X PUT -k http://localhost:39081/api/caches/clearall

returns:

{}

Setting the disabled state a specific cache

Disabling a cache requires posting the name and a boolean parameter indicating whethere it should be in a disabled state.

curl -s -X POST -k http://localhost:39081/api/caches/setdisabled -d '{"name": "disks/c", "disabled": true}'

returns:

{}

Configuring / setting cache size limits

Limits for each cache type on a host can be set through the REST API. The limit parameter is a percentage of available space on the local device named in the POST data for the request.

For example, to set the cache on physical drive C on the local host to 11% of available space:

curl -s -X POST -k http://localhost:39081/api/caches/setlimit -d '{"name": "disks/c", "limit": 11}'

returns:

{}