Cache methods which work with most tooling

The Generic Cache is a part of the Buildless API which does the actual work of caching of build artifacts. It is one of the options you can choose when integrating tooling directly with the API.

It's called Generic because this way of accessing the cache is largely blind to the context that goes into a given cache key. Methods in this section treat cached data as opaque. How you compute your cache keys is entirely up to you.

The API interface

It really could not be simpler:

- Step 1: Cache fetch & miss ------------------------------------------------------------------

GET /cache/generic/abc123 ---> service
client <------ HTTP 404 ("I haven't seen the key abc123 before")


- Step 2: Cache put ---------------------------------------------------------------------------

PUT /cache/generic/abc123 ---> service
Content-Type: (anything)
Content-Length: 123

(Buncha data here)

client <------ HTTP 202 ("Okay, I've stored your data at key abc123")


- Step 3: Cache fetch & hit -------------------------------------------------------------------

GET /cache/generic/abc123 ---> service
client <------ HTTP 200 ("Yep, here is the data for key abc123")

-----------------------------------------------------------------------------------------------

The API imposes some limitations which are good to review.

API compatibility

The Generic Cache is drop-in compatible with the following tools:

Tool / ecosystemSupportedTested
Gradle: Kotlin, JVM, Node✅ Fully supported✅ Continuously tested
CCache: C, C++, ASM, etc.✅ Fully supported✅ Continuously tested

There are setup guides available for Gradle, CCache, and the API itself to help you get started.

API methods

See below for a summary of API methods which are part of the Generic Cache feature:

GET /cache/generic/{key}: Fetch by key

This method fetches a blob from the generic cache, addressed by a string key assigned by the client at the time it is stored (see Put by key for more information).

PUT /cache/generic/{key}: Put by key

This method stores a blob of data in the generic cache for consumption later by any cache client, addressed by a string key which is assigned client-side. How keys are assembled is a bit of an art and science; we have docs coming soon to help this case.

Most build tools which support build caching are already equipped with cache key generation logic, so you probably don't need to worry about this.

DELETE /cache/generic/{key}: Flush by key

Flush an individual key from the cache. The key is deleted from all cache nodes. There is no need to precede a PUT with a DELETE in order to update data; although updates against existing keys are discouraged in Buildless' model, PUT calls always overwrite, so you can just call it directly to achieve the same effect without the cost of two calls.