How to use Cache.horse
https://api.cache.horse/get?api_key=YOUR_API_KEY
&uri=URI
&uris=URI1,URI2,URI3
&refresh=true|false
&ttl=TIME_IN_MILLISECONDS
Parameters
api_key
: get one by signing up.uri
: a single string of a valid url.uris
: a pipe-separated (|
) list in string format of valid urls.ttl
: the length of time this request will be cached. Defaults to3600000
(1 day).refresh
: force a refresh of the cache. New data will be fetched from the url(s) and returned.
Response
When you request a single URL, the response will simply mirror the resource. For example if your resource returns:
{ "success": true }
Our API will return the same:
However, in the case of multiple URLs, we will return each resource to you in an array. Each element in the array will contain, first, the requested URL, followed by the received payload. For example, take this request:
/get?uris=https://example.com/1|https://example.com/2
Let’s assume each of the responses are { "number": 1 }
& { "number": 2 }
. Our API will return:
[
[
"https://example.com/1",
{ "number": 1 }
],
[
"https://example.com/2",
{ "number": 2 }
]
]
Authentication
All requests require an API key. You can get one by signing up.
Per-API key cache
Each cache is unique to each API key. This means that if two clients request the same resource, they will not share the same cached result.
Formatting the uri
/uris
parameter
Cache.horse accepts valid URIs that are in FQDN format.
- The URI is restricted to
http
/https
protocols. - The URI can contain query parameters.
- The URI must be URL encoded.
URL encoding
You should always URL encode query parameters. Consider the following example:
https://api.cache.horse/get?uri=https://httpbingo.org/json?my_param=true&other_param=false
URL parsers can have trouble understanding, in the above example, if &another_param=false
refers to the request or to the parameter!
The solution is to encode it. This can be done in Javascript (frontend or backend) with the following code:
encodeURLComponent('https://httpbingo.org/json?my_param=true&other_param=false');
// => 'https%3A%2F%2Fhttpbingo.org%2Fjson%3Fmy_param%3Dtrue%26other_param%3Dfalse'
A note on formats
Cache.horse is made to cache and combine API requests. We are not made for general scraping of the internet. As such, we restrict what content we allow to ensure that we are not used as a proxy.
The following formats are allowed:
- JSON
- XML (coming soon)
All other formats will be rejected.
Errors
Errors are returned in JSON format:
{ "error": "error_string" }
Additionally, the request will return a corresponding HTTP status code.
bad_request
|400
: one of the query parameters was malformed or missing.unauthorized
|401
: you are missing (or have an invalid) API key.forbidden
|403
: you’re in the wrong neighbourhood ;)not_found
|404
: the endpoint you’re trying to call doesn’t exist.not_acceptable
|406
: we are not able to serve the requested resource(s), most likely due to them being invalid.request_timeout
|408
: the resource(s) you’re trying to get timed out and returned no data.payload_too_large
|413
: the resource is too big to be cached/returned.unsupported_media_type
|415
: we only allow JSON. Everything else will return this error.misdirected_request
|421
: the resource(s) you asked for refuse to respond. This is likely due to an error (such as an authentication error).too_many_requests
|429
: most likely, you’ve run out of quota.internal_server_error
|500
: something went wrong on our side.