Management API

This guide will get you all set up and ready to use BadgerCache Management API.

Use Case

The Management API can be used to manually create and update cache keys from an external API. For example, if a product was created in a ecommerce CRM, the cache key could automatically be setup in BadgerCache using the API.

Setup for Data Sources

A data source is required to create a cache key. Because of all the useful validation in the BadgerCache UI, we do not currently support using the Management API to create data sources. However, you can identify the ID of the data source to use for the new key by accessing that data source from the edit screen. The ID should be in the address bar.

Setup for Tasks

Like the data source, we don't currently support creating tasks through the management API due to the complexity involved with validation.

To effectively automate the management of new cache keys, a task could be setup with a key pattern. For example, if you setup a task with a key pattern product: and then used the management API to create a cache key called product:12:, that key would automatically be kept updated by the task. This is the best method to automate key creation and tasks.

Create an API Key

Currently, an API key is required to use the BadgerCache API. This key is for backend calls only. The keys are scoped to each individual store environment.

Navigate to Store > Settings > API Keys to create an API key. Provide a label for the key to identify it. Only users of the Admin or Owner levels can create API keys.

The API keys do not expire. For security purposes, is a good idea to regenerate keys on a schedule.

Using the API

The BadgerCache API is located at https://api.badgercache.com. The BadgerCache API is free and unmetered. But we do have rate limiting across the application at 400 requests per second.

When authenticating with the API, it accepts an Authorization header and a bearer token matching Bearer {{api key}}, where the handlebars are replaced with your secret key.

Cache Key Properties

Name
id
Type
integer
Description
Unique identifier for the cache key.
Name
store_id
Type
integer
Description
Unique identifier for the store.
Name
key
Type
string
Description
The key name as a string.
Name
size
Type
integer
Description
Size of the cached value in bytes. This value cannot be set by the client.
Name
datasource_id
Type
integer
Description
Unique identifier for the data source.
Name
datasource_variables
Type
JSON array
Description
This is a JSON array of key value pairs used as variables in the data source request.
Name
updated_at
Type
timestamp
Description
Timestamp of when the cache key was last updated.
Name
created_at
Type
timestamp
Description
Timestamp of when the cache key was created.

POST/v1/store/{storeId}/cache-key

Create a Cache Key

This endpoint allows you to programmatically create a cache key.

Required attributes

Name
store_id
Type
integer
Description
Unique identifier for the store. The API token must have access to the store.
Name
key
Type
string
Description
The key name as a string. Max size 1024 bytes.
Name
datasource_id
Type
integer
Description
Unique identifier for the data source.
Name
datasource_variables
Type
JSON array
Description
This is a JSON array of key value pairs used as variables in the data source request. This is only required if the data source has variables.

Optional attributes

Name
value
Type
string
Description
The value can be passed as a stringified JSON object or string. The maximum size of the value key is 25 MB. Depending on the store setup, the value will update the store's linked Redis instance or push an update to a webhook.

Request

POST

/v1/store/{storeId}/cache-key

curl -X POST https://api.badgercache.com/v1/store/35/cache-key \
  -H "Authorization: Bearer {token}" \
  -d store_id=35 \
  -d key="product:category:1:" \
  -d datasource_id=11

Response

{
  "result": {
    "id": 585,
    "store_id": 35,
    "key": "product-category-1",
    "size": 0,
    "datasource_id": 11,
    "datasource_variables": [],
    "created_at": "2023-06-27T03:27:17.944Z",
    "updated_at": "2023-06-27T03:27:17.944Z"
  }
}

PATCH/v1/store/{storeId}/cache-key/{keyId}

Update a Cache Key

This endpoint allows you update a cache key. It's primary use case is updating the value manually in the cache. The key name cannot be updated since this would create syncing problems with the external cache.

Optional attributes

Name
datasource_id
Type
integer
Description
Unique identifier for the data source.
Name
datasource_variables
Type
JSON array
Description
This is a JSON array of key value pairs used as variables in the data source request. This is only required if the data source has variables.
Name
value
Type
string
Description
The value can be passed as a stringified JSON object or string. The maximum size of the value key is 25 MB. Depending on the store setup, the value will update the store's linked Redis instance or push an update to a webhook.

Request

PATCH

/v1/store/{storeId}/cache-key/{keyId}

curl -X PATCH https://api.badgercache.com/v1/store/35/cache-key/585 \
  -H "Authorization: Bearer {token}" \
  -d value="Test value for cache key"

Response

{
  "result": {
    "id": 585,
    "store_id": 35,
    "key": "product-category-1",
    "size": 0,
    "datasource_id": 11,
    "datasource_variables": [],
    "created_at": "2023-06-27T03:27:17.944Z",
    "updated_at": "2023-06-27T03:27:17.944Z"
  }
}

DELETE/v1/store/{storeId}/cache-key/{keyId}

Delete a Cache Key

This endpoint allows you delete a cache key. The key will also be deleted from Redis if the option is setup with the store. For webhook setups, the key will need to be deleted manually.

Request

DELETE

/v1/store/{storeId}/cache-key/{keyId}

curl -X DELETE https://api.badgercache.com/v1/store/35/cache-key/585 \
  -H "Authorization: Bearer {token}"