NAV
python shell

Getting started

Welcome to the Warpcache API documentation! You can use our API to configure most on our platform. You can create, update and delete properties and also retrieve data usage detail and invalidate content.

We have language examples in Shell, and Python. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Our API uses an API token or your login session from our management portal. You can find your Warpcache API key at our portal.

In the python examples we use the requests library client to set up a session with the API.

Glossary

Keyword Definition
CDN A Content Delivery Network. We use multiple to guarantee 100% uptime
vhost /
property
An entry in our multi-cdn solution for a domain name. E.g.: example.cdn.warpcache.com
origin The url that contains files that will be pulled & cached by CDN’s. E.g. http://o.example.com
domain name The url which you can use to pull your files through the multi-cdn solution. E.g. http://cdn.example.com
flush API representation of a flush/purge request to connected CDN providers to clear cache for an object
purge See flush
invalidation See flush

Formatting

API formatting can be manipulated through the format query parameter.

Our API supports multiple formatting types:

Parameter Value Default Description
format json true Response will be in JSON format
format api false Response will be in HTML format
format xml false Response will be in XML format

Errors

Warpcache uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing), and codes in the 5xx range indicate an error with Warpcache’s servers.

The Warpcache API has the following error codes:

Error Code Meaning
400 - Bad Request Often missing a parameter
401 - Unauthorized No valid API key provided
403 - Forbidden The resource requested is unavailable for the API key provided
404 - Not Found The specified resource doesn’t exist
405 - Method Not Allowed Check the HTTP method
406 - Not Acceptable The requested format isn’t supported
500 - Internal Server Error We had a problem with our server
503 - Service Unavailable We’re temporarially offline for maintanance

Authentication

Authentication works by supplying a API token in the request header. You can obtain a token in the portal. If you’re logged in on our management portal, you can browse our API using a cookie session.

We recommend using an API token for authorisation by systems.

The key should be prefixed by the string literal “Token”, with whitespace separating the two strings.


import requests

API_TOKEN = 'YOUR_API_TOKEN'
API_BASE = 'https://my.warpcache.com/api/v1/'

api = requests.session()
api.headers['Authorization'] = 'Token {0}'.format(token)

index = api.get(API_BASE).json()
print(index)

# That's easy!
curl -X GET -H 'Authorization: Token YOUR_API_TOKEN' \
    https://my.warpcache.com/api/v1/

Make sure to replace YOUR_API_TOKEN with the token generated in the portal

Vhosts

This endpoint allows you to list, create and update information about vhosts.

LIST


""" Assuming we keep our api and api_base
variables from the authentication example: """

url = API_BASE + 'vhost/'
vhosts = api.get(url).json()
# With shell, you can just pass the correct header with each request
curl "/api/v1/vhosts/" \
  -H "Authorization: YOUR_API_TOKEN"

Example response:

[ { 
    "name" : "example",
    "domain_name" : "example.cdn.warpcache.com",
    "id" : 1,
    "origin_url" : "https://www.warpcache.com",
    "profile" : { "id" : 2,
        "name" : "Standard"
      },
      "properties" : [{ 
        "cname" : "example.cdn.warpcache.com",
        "gzip" : true,
        "host_header" : "",
        "id" : 1,
        "override_hostheader" : false,
        "ssl" : true,
        "ttl" : 3600
    }],
    "state" : "in_progress",
    "url" : "https://my.warpcache.com/api/v1/vhosts/1/"
  } ]

Returns a list of with vhost data objects.

GET https://my.warpcache.com/api/v1/vhosts/

GET


""" Assuming we keep our api and API_BASE
variables from the authentication example: """

vhost_id = 1
url = API_BASE + 'vhost/' + vhost_id
vhosts = api.get(url).json()
# With shell, you can just pass the token in a header with each request
curl "/api/v1/vhosts/1" \
  -H "Authorization: YOUR_API_TOKEN"

Example response:

{ "domain_name" : "example.cdn.warpcache.com",
  "id" : 1,
  "name" : "example",
  "origin_url" : "https://www.warpcache.com",
  "profile" : { "id" : 2,
      "name" : "Standard"
    },
    "properties" : [{
        "cname" : "example.cdn.warpcache.com",
        "gzip" : true,
        "host_header" : "",
        "id" : 1,
        "override_hostheader" : false,
        "ssl" : true,
        "ttl" : 3600
      }],
  "state" : "in_progress",
  "url" : "https://my.warpcache.com/api/v1/vhosts/1/"
}

Returns a single vhost object.

GET https://my.warpcache.com/api/v1/vhosts/1/

POST


""" Assuming we keep our api and API_BASE
variables from the authentication example: """

url = API_BASE + 'vhost/'

data = {
    'domain_name': 'another.example.com',
    'origin_url': 'http://o.example.com/',
    'monitor_url': '/favicon.ico'
    'name': 'another'
}
new_vhost = api.post(url, data=data).json()
``

```shell
curl "/api/v1/vhosts/" \
  -H "Authorization: YOUR_API_TOKEN" \
  --data ""

Example response:


{ "domain_name" : "another.example.com",
  "id" : 2,
  "name" : "another",
  "origin_url" : "http://o.example.com",
  "profile" : { "id" : 2,
      "name" : "Standard"
    },
  "properties" : [  ],
  "state" : "in_progress",
  "url" : "https://my.warpcache.com/api/v1/vhosts/2/"
}

This method allows you to create vhosts.

POST https://my.warpcache.com/api/v1/vhosts/

Post Parameters

Parameter Required Description
domain_name true References the CDN vhost. This is the hostname the user would browse to to retrieve files.
name true Nice name by which user can identify the vhost (no functional purpose).
origin_url true URL that references the origin. Where the CDN will get the content fromContains protocol, domain name (fqdn), port (optional) and the full path.
monitor_url false A path relative to the origin that we can test to know the state of the cdns in your mix

VhostProperties

LIST


""" Assuming we keep our api and API_BASE
variables from the authentication example: """

url = API_BASE + 'vhostproperties/'
new_vhost = api.get(url).json()
# With shell, you can just pass the correct header with each request
curl "/api/v1/vhosts/" \
  -H "Authorization: YOUR_API_TOKEN" \

Example response:


[{
    "id": 1,
    "cname": "example.cdn.warpcache.com",
    "ttl": 300,
    "gzip": false,
    "querystring": false,
    "ssl": false,
    "override_hostheader": false,
    "host_header": "",
    "content_protection": false,
    "cors": false
},{
    "id": 2,
    "cname": "api.cdn.warpcache.com",
    "ttl": 300,
    "gzip": true,
    "querystring": true,
    "ssl": false,
    "override_hostheader": false,
    "host_header": "",
    "content_protection": false,
    "cors": false
}]

List of all vhost property objects.

GET https://my.warpcache.com/api/v1/vhostproperties/

GET


""" Assuming we keep our api and API_BASE
variables from the authentication example: """

vhost_property_id = 1
url = API_BASE + 'vhostproperties/' + vhost_property_id
new_vhost = api.get(url).json()
# With shell, you can just pass the correct header with each request
curl "/api/v1/vhostproperties/1" \
  -H "Authorization: YOUR_API_TOKEN" \

Example response:


{
    "id": 1,
    "cname": "example.cdn.warpcache.com",
    "ttl": 300,
    "gzip": true,
    "querystring": true,
    "ssl": false,
    "override_hostheader": false,
    "host_header": "",
    "content_protection": false,
    "cors": false
}

Show vhost property object for vhost id id.

GET https://my.warpcache.com/api/v1/vhostproperties/ id /

PATCH


""" Assuming we keep our api and API_BASE
variables from the authentication example: """

vhost_property_id = 1
data = {
    'ttl': '300',
    'gzip': True
}
url = API_BASE + 'vhostproperties/' + vhost_property_id

vhost_property = api.put(url).json()
# With shell, you can just pass the correct header with each request
curl "/api/v1/vhostproperties/1" \
  -H "Authorization: YOUR_API_TOKEN" \

Example response:


{
    "id": 1,
    "cname": "example.cdn.warpcache.com",
    "ttl": 300,
    "gzip": true,
    "querystring": true,
    "ssl": false,
    "override_hostheader": false,
    "host_header": "",
    "content_protection": false,
    "cors": false
}

This method allows you to update vhosts properties.

PATCH https://my.warpcache.com/api/v1/vhostproperty/ id /

Data

Parameter Required Read only Description
cname false x The hostname to which you link your domain e.g. foo.cdn.warpcache.com
gzip false Boolean. If enabled, the CDNs will be set to compress objects
querystring false When enabled the CDN will use the query string as part of the cache key
ssl false Indicates whether a vhost is also available on SSL
secure content false Secure your content with access tokens, only a limited amount of cdn’s support this feature.
large_files false Optmises CDN selection for the delivery of files larget than 100kb
override_hostheader false By default the Host header used to retrieve objects from origin is the origin hostname. Set to TRUE to use the name of the vhost in requests to origin
host_header false Allows you to specify the Host header to be used in requests to origin

Flush

With this endpoint you can create a request to flush / purge / invalidate an object from all connected cdn’s.

Domain name cdn.example.com
Origin url http://o.example.com
Label example
Cname example.cdn.warpcache.com

Will let you flush on the domain name http:// cdn.example.com /

LIST


""" Assuming we keep our api and API_BASE
variables from the authentication example: """

url = API_BASE + 'flush/'
new_vhost = api.get(url).json()
# With shell, you can just pass the correct header with each request
curl "/api/v1/vhosts/" \
  -H "Authorization: YOUR_API_TOKEN" \

Example response:


{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 2,
      "flushes": [
        2
      ],
      "urls": [
        "http://cdn.example.com/selfie.jpg",
        "http://cdn.example.com/team_photo.jpg"
      ],
      "owner": 1
    },
    {
      "id": 1,
      "flushes": [
        1
      ],
      "urls": [
        "http://cdn.example.com/selfie.jpg"
      ],
      "owner": 1
    },
]

List of all flushes from your organization.

GET https://my.warpcache.com/api/v1/flush/

GET


""" Assuming we keep our api and API_BASE
variables from the authentication example: """

flush_id = 1
my_flush = api.get(url+'flush/' + flush_id)

# With shell, you can just pass the correct header with each request
curl "/api/v1/flush/1" \
  -H "Authorization: YOUR_API_TOKEN" \

Example response:


{
  "id": 1,
  "flushes": [
    1
  ],
  "urls": [
    "http://example.cdn.warpcache.com/api.txt"
  ],
  "owner": 1
}

Show vhost property object for vhost id id.

GET https://my.warpcache.com/api/v1/flush/ id /

POST


""" Assuming we keep our api and API_BASE
variables from the authentication example: """

import json
my_flush = api.post(url+'flush/', data=json.dumps(
    {
        'urls': [
            "http://example.cdn.warpcache.com/test.txt"
        ]
    }),
    headers={
        'Content-Type': 'application/json'
    }
)

# With shell, you can just pass the correct header with each request
curl "/api/v1/flush/1" \
  -H "Authorization: YOUR_API_TOKEN" \

Example response:

{
  "id": 1,
  "flushes": [
    1
  ],
  "urls": [
    "http://example.cdn.warpcache.com/api.txt"
  ],
  "owner": 1
}

This method allows you to create a flush request

POST https://my.warpcache.com/api/v1/flush/

Post Parameters

Parameter Required Description
urls true The URL of the object you want to flush

FlushAll

To flush all objects on all enabled cdns you can call the /flushall/ endpoint.

POST https://my.warpcache.com/api/v1/flushall/


""" Assuming we keep our api and API_BASE
variables from the authentication example: """

import json
my_flush = api.post(API_BASE+'flushall/', data=json.dumps(
    {
        'urls': [
            "http://example.cdn.warpcache.com"
        ]
    }),
    headers={
        'Content-Type': 'application/json'
    }
)

# With shell, you can just pass the correct header with each request
curl "/api/v1/flush/1" \
  -H "Authorization: YOUR_API_TOKEN" \
  -d '{"urls":["example.cdn.warpcache.net"]}'

Flushstatus

Use this to retrieve the status of your flushes

LIST


""" Assuming we keep our api and API_BASE
variables from the authentication example: """

url = API_BASE + 'flushstatus/'
flushstatusses = api.get(url).json()

Example response:


[
  {
    "url": "https://my.warpcache.com/api/v1/flush/2/",
    "id": "https://my.warpcache.com/api/v1/flushstatus/2/",
    "flushrequest": 2,
    "error": "one or more cdns have failed to flush",
    "result": {
      "ready": true,
      "total": 2,
      "done": 2,
      "results": [
        [
          "CDN Provider",
          "flushed"
        ],
        [
          "CDN Provider 2",
          "flushed"
        ]
      ]
    },
    "state": "failed",
    "filenames": "[u'/test.txt', '/api.txt']",
    "created": "2015-07-13T08:49:03Z",
    "updated": "2015-07-13T08:49:04Z",
    "vhost": "https://my.warpcache.com/api/v1/vhosts/1/"
  },
  {
    "url": "https://my.warpcache.com/api/v1/flush/1/",
    "id": "https://my.warpcache.com/api/v1/flushstatus/1/",
    "flushrequest": 1,
    "error": "",
    "result": {
      "ready": true,
      "total": 1,
      "done": 2,
      "results": [
        [
          "CDN Provider",
          "flushed"
        ],
        [
          "CDN Provider 2",
          "flushed"
        ]
      ]
    },
    "state": "finished",
    "filenames": "[u'/test.txt']",
    "created": "2015-07-13T08:50:45Z",
    "updated": "2015-07-13T08:50:46Z",
    "vhost": "https://my.warpcache.com/api/v1/vhosts/1/"
  }
]

Retrieves a list of status/details for a flush request.

GET https://my.warpcache.com/api/v1/flushstatus/

GET


""" Assuming we keep our api and API_BASE
variables from the authentication example: """

url = API_BASE + 'flushstatus/2/'
flushstatus = api.get(url).json()

Example response:


{
  "url": "https://my.warpcache.com/api/v1/flush/2/",
  "id": "https://my.warpcache.com/api/v1/flushstatus/2/",
  "flushrequest": 2,
  "error": "one or more cdns have failed to flush",
  "result": {
    "ready": true,
    "total": 2,
    "done": 2,
    "results": [
      [
        "CDN Provider",
        "flushed"
      ],
      [
        "CDN Provider 2",
        "flushed"
      ]
    ]
  },
  "state": "failed",
  "filenames": "[u'/test.txt', '/api.txt']",
  "created": "2015-07-13T08:49:03Z",
  "updated": "2015-07-13T08:49:04Z",
  "vhost": "https://my.warpcache.com/api/v1/vhosts/1/"
}

Retrieves a single status/detail report for a flush request.

GET https://my.warpcache.com/api/v1/flushstatus/

Traffic

Get information on traffic usage

LIST


""" Assuming we keep our api and API_BASE
variables from the authentication example: """

url = API_BASE + 'traffic/'
traffic = api.get(url).json()

Example response:


[
    {
        "usage": "1262.93",
        "quantity": "gb",
        "text": "1262.93 gb",
        "vhost": {
            "domain_name": "example.cdn.warpcache.com",
            "id": 1,
            "name": "example",
            "origin_url": "http://o.warpcache.com",
            "state": "active",
            "url": "https://my.warpcache.com/api/v1/vhosts/1/",
            "properties": [],
            "profile": {
                "name": "Standard",
                "id": 2
            }
        }
    },
    {
        "usage": "1262.93",
        "quantity": "gb",
        "text": "1262.93 gb",
        "vhost": {
            "domain_name": "cdn.example.com",
            "id": 2,
            "name": "mycompany",
            "origin_url": "http://o.example.com",
            "state": "active",
            "url": "https://my.warpcache.com/api/v1/vhosts/2/",
            "properties": [],
            "profile": {
                "name": "Standard",
                "id": 2
            }
        }
    }
]

Lists all usage for all vhosts

GET https://my.warpcache.com/api/v1/traffic/

GET


{
    "usage": "1262.93",
    "quantity": "gb",
    "text": "1262.93 gb",
    "vhost": {
        "domain_name": "example.cdn.warpcache.com",
        "id": 1,
        "name": "example",
        "origin_url": "http://o.warpcache.com",
        "state": "active",
        "url": "https://my.warpcache.com/api/v1/vhosts/1/",
        "properties": [],
        "profile": {
            "name": "Standard",
            "id": 2
        }
    }
}

Retrieve usage for one vhost

GET https://my.warpcache.com/api/v1/traffic/ id /

Query Parameters

Parameter Required Default Description
start_date false First day of the current month Start date for fetching traffic usage. Format: dd-mm-yyyy
end_date false Today End date for fetching traffic usage. Format: dd-mm-yyyy