IronCache API Reference

IronCache provides a REST/HTTP API to allow you to interact programmatically with your caches on IronCache.

Endpoints

Authentication

IronCache uses OAuth2 tokens to authenticate API requests. All methods require authentication unless specified otherwise. You can find and create your API tokens in the HUD. To authenticate your request, you should include a token in the Authorization header for your request or in your query parameters. Tokens are universal, and can be used across services.

Note that each request also requires a Project ID to specify which project the action will be performed on. You can find your Project IDs in the HUD. Project IDs are also universal, so they can be used across services as well.

Example Authorization Header: Authorization: OAuth abc4c7c627376858

Example Query with Parameters: GET https://cache-aws-us-east-1.iron.io/1/projects/{Project ID}/caches?oauth=abc4c7c627376858

Notes:

• Be sure you have the correct case, it’s OAuth, not Oauth.
• In URL parameter form, this will be represented as: ?oauth=abc4c7c627376858

Requests

Requests to the API are simple HTTP requests against the API endpoints.

All request bodies should be in JSON format, with Content-Type of application/json.

Base URL

All endpoints should be prefixed with the following:

https://{Host}.iron.io/{API Version}/

API Version Support : IronCache API supports version 1

The domains for the clouds IronCache supports are as follows:

Pagination

For endpoints that return lists/arrays of values:

• page - The page of results to return. Default is 0. Maximum is 100.
• per_page - The number of results to return. It may be less if there aren’t enough results. Default is 30. Maximum is 100.

Responses

All responses are in JSON, with Content-Type of application/json. A response is structured as follows:

{ "msg": "some success or error message" }

Status Codes

The success or failure of a request is indicated by an HTTP status code. A 2xx status code indicates success, whereas a 4xx or 5xx status code indicates an error.

Specific endpoints may provide other errors in other situations.

When there’s an error, the response body contains a JSON object similar to the following:

{ "msg": "reason for error" }

Exponential Backoff

When a 503 error code is returned, it signifies that the server is currently unavailable. This means there was a problem processing the request on the server-side; it makes no comment on the validity of the request. Libraries and clients should use exponential backoff when confronted with a 503 error, retrying their request with increasing delays until it succeeds or a maximum number of retries (configured by the client) has been reached.

List Caches

Get a list of all caches in a project. 100 caches are listed at a time. To see more, use the page parameter.

Endpoint

URL Parameters

• Project ID: Project these caches belong to

Optional URL Parameters

• page: The 0-based page to view. The default is 0. See pagination.

Response

[
  {
    "project_id": "PROJECT ID",
    "name": "CACHE NAME"
  },
  {
    "project_id": "PROJECT ID",
    "name": "CACHE NAME"
  }
]

Get Info About a Cache

This call gets general information about a cache.

Endpoint

URL Parameters

• Project ID: Project the cache belongs to
• Cache Name: The name of the cache

Response

{
  "size": "cache size"
}

Delete a Cache

Delete a cache and all items in it.

Endpoint

URL Parameters

• Project ID: Project the cache belongs to
• Cache Name: The name of the cache

Response

{
  "msg": "Deleted."
}

Clear a Cache

Delete all items in a cache. This cannot be undone.

Endpoint

URL Parameters

• Project ID: Project the cache belongs to
• Cache Name: The name of the cache whose items should be cleared.

Response

{
  "msg": "Cleared."
}

Put an Item into a Cache

This call puts an item into a cache.

Endpoint

URL Parameters

• Project ID: The project these items belong to.
• Cache Name: The name of the cache. If the cache does not exist, it will be created for you.
• Key: The key to store the item under in the cache.

Item Object

Each item object should contain the following keys:

Required

• value: The item’s data

Optional

• expires_in: How long in seconds to keep the item in the cache before it is deleted. Maximum is 604,800 seconds (7 days).
• replace: If set to true, only set the item if the item is already in the cache. If the item is not in the cache, do not create it.
• add: If set to true, only set the item if the item is not already in the cache. If the item is in the cache, do not overwrite it.
• cas: If set, the new item will only be placed in the cache if there is an existing item with a matching key and cas value. An item’s cas value is automatically generated and is included when the item is retrieved.

Request

{
  "value": "This is my cache item.",
  "expires_in": 86400,
  "replace": true
}

Response

{
  "msg": "Stored."
}

Increment an Item’s value

This call increments the numeric value of an item in the cache. The amount must be a number and attempting to increment non-numeric values results in an error. Negative amounts may be passed to decrement the value. The increment is atomic, so concurrent increments will all be observed.

Endpoint

URL Parameters

• Project ID: The project the item belongs to.
• Cache Name: The name of the cache. If the cache does not exist, it will be created for you.
• Key: The key of the item to increment.

Request Parameters

The request body should contain the following keys:

Required

• amount: The amount to increment the value, as an integer. If negative, the value will be decremented.

Request

{
  "amount": 10
}

Response

{
  "msg": "Added",
  "value": 132
}

Get an Item from a Cache

This call retrieves an item from the cache. The item will not be deleted.

Endpoint

URL Parameters

• Project ID: The project the cache belongs to.
• Cache Name: The name of the cache the item belongs to.
• Key: The key the item is stored under in the cache.

Response

{
  "cache": "CACHE NAME",
  "key": "ITEM KEY",
  "value": "ITEM VALUE",
  "cas": "12345"
}

Delete an Item from a Cache

This call will delete the item from the cache.

Endpoint

URL Parameters

• Project ID: The project the cache belongs to.
• Cache Name: The name of the cache the item belongs to.
• Key: The key the item is stored under in the cache.

Response

{
  "msg": "Deleted."
}