Documentation

Overview

Pageload is a proxy that filters and optimises your JPEG, GIF, PNG, SVG, JS, and CSS assets on-the-fly.

Pageload provides you with a unique proxy host which sits between your server and your users and optimises assets to speed up delivery and save bandwidth.

http://site.cl.pageload.io/header.jpg http://site.com/header.jpg

It's recommended that you setup a CNAME record to the proxy host, e.g.

cdn.example.com example.cl.pageload.io.

That way, your assets are available via your own subdomain

http://cdn.example.com/images/header.jpg

Filters

Optimisation

Pageload will optimise and/or minify JPEG, GIF, PNG, SVG, JS and CSS files, with support for additional formats coming soon.

Resizing images

Images can be resized and optimised on the fly by appending the desired image dimensions to the end of the URL after a semicolon.

  • ;(width)x(height) - resize the image to an exact width and height. The image is cropped from the centre if the requested aspect ratio differs from the original.
  • ;(width)x - resize the image to an exact width while maintaining aspect ratio.
  • ;x(height) - resize the image to an exact height while maintaining aspect ratio.

The following example URLs assume that a 600x200 image exists at http://mysite.com/image/header.jpg.

http://mysite.cl.pageload.io/image/header.jpg;150x50 - resize the image to be 150px wide and 50px high. Since this maintains aspect ratio, no cropping is required.

http://mysite.cl.pageload.io/image/header.jpg;150x - resize the image to be 150px wide while maintaining aspect ratio. Note that the image is still 50px in height since there's no aspect ratio change.

http://mysite.cl.pageload.io/image/header.jpg;x150 - resize the image to be 150px high while maintaining aspect ratio. The resulting image would be 450px wide since there's no aspect ratio change.

http://mysite.cl.pageload.io/image/header.jpg;50x50 - resize the image to be 50px wide and 50px high. Since this operation would modify the aspect ratio, the largest square is cropped from the centre of the image (in this case, it would be 200px by 200px) and then resized to be 50px by 50px.

Caching

Header control

On the dashboard, click Edit next to the host that you wish to modify cache header settings for. There are four options for handling Expires and Cache-Control headers.

Pass through origin headers

Pageload will pass the origin Expires and Cache-Control headers to the requesting client, if they are provided by the origin. Pageload will not add the headers if they are missing.

Override origin headers unless the resource is uncacheable

Pageload will send custom Expires and Cache-Control headers to the requesting client based on the specified time period that you provide. Pageload will disregard origin Expires and Cache-Control headers, unless they signal that the resource should not be cached. A resource is deemed to be uncacheable if either the Expires header is in the past, the Cache-Control header contains any of no-cache, no-store, private, or max-age=0, or it contains a cookie via a Set-Cookie header.

Always override origin headers

Pageload will send custom Expires and Cache-Control headers to the requesting client based on the specified time period that you provide. Pageload will ignore all cache headers received from the origin.

Add headers if not provided by the origin

If the origin provides an Expires or Cache-Control header, then they will be sent to the requesting client. If neither is provided by the origin, then Pageload will send custom Expires and Cache-Control headers to the requesting client based on the specified time period that you provide.

Purge

On the dashboard, click Purge next to the host that you wish to purge files from. Enter one path (e.g. /path/to/image.jpg) per line. You can purge up to 100 files at a time using the provided form. There's also an API call you can make to purge files.

API

Authentication

The API lives at https://pageload.io/api/1 and is available to users that authenticate via basic HTTP auth.

API keys can be generated and revoked on the API Key Management page. To authenticate using HTTP auth, specify an API key as the username and an empty password (equivalent to curl -u '<key>:').

The following examples use curl with the example key: acZsjXjAHh9aLXKhl4gxSxhhhw9Mj3xm

GET /api/1/hosts

List all hosts associated with the account.

$ curl https://pageload.io/api/1/hosts -u acZsjXjAHh9aLXKhl4gxSxhhhw9Mj3xm:
          
[
  {
    "id": 1,
    "proxy_host": "foo.cl.pageload.io",
    "cdn_host": null,
    "origin": "foo.com"
  },
  {
    "id": 2,
    "proxy_host": "bar.cl.pageload.io",
    "cdn_host": "bar.cdn.pageload.io",
    "origin": "bar.net"
  }
]
          
        

Filter & optimise

POST /api/1/filter/:path?

Filter and/or optimise an asset manually.

$ curl -X POST https://pageload.io/api/1/filter \
    -u acZsjXjAHh9aLXKhl4gxSxhhhw9Mj3xm: \
    -H 'Content-Type: image/jpeg' \
    --data-binary @- < foobar.jpg > foobar-output.jpg

The path is optional and can be used to specify filter parameters.

$ curl -X POST https://pageload.io/api/1/filter/foobar.jpg;150x150 \
    -u acZsjXjAHh9aLXKhl4gxSxhhhw9Mj3xm: \
    -H 'Content-Type: image/jpeg' \
    --data-binary @- < foobar.jpg > foobar-thumbnail.jpg

Purge

GET /api/1/hosts/:host/purge/:path

Purge a single file from a host.

$ curl https://pageload.io/api/1/hosts/1/purge/images/foo.jpg \
    -u acZsjXjAHh9aLXKhl4gxSxhhhw9Mj3xm:

Purge up to 100 files at a time.

$ curl -X POST https://pageload.io/api/1/hosts/1/purge \
    -u acZsjXjAHh9aLXKhl4gxSxhhhw9Mj3xm: \
    -H 'Content-Type: application/json' \
    -d '{ "files": [ "/images/foo.jpg", "/images/bar.jpg" ] }'

Statistics

GET /api/1/stats/:year/:month

Get account statistics for the specified month.

$ curl https://pageload.io/api/1/stats/2013/09 \
    -u acZsjXjAHh9aLXKhl4gxSxhhhw9Mj3xm:
{
  "requests": 563812,
  "filter_operations": 345918,
  "bytes_in": 14554555295,
  "bytes_saved": 4891107569,
  "bytes_out": 9663447726
}

GET /api/1/daily-stats/:year/:month

Get account statistics for the specified month, broken down by day.

$ curl https://pageload.io/api/1/daily-stats/2013/09 \
    -u acZsjXjAHh9aLXKhl4gxSxhhhw9Mj3xm:
[
  {
    "day": 1,
    "month": 9,
    "year": 2013,
    "data": {
      "requests": 9906,
      "filter_operations": 3012,
      "bytes_in": 641238829,
      "bytes_saved": 190415522,
      "bytes_out": 450823307
    }
  },
  {
    "day": 2,
    "month": 9,
    "year": 2013,
    "data": {
      "requests": 9738,
      "filter_operations": 2952,
      "bytes_in": 915389032,
      "bytes_saved": 312597448,
      "bytes_out": 602791584
    }
  },
  ...
]

GET /api/1/hosts/1/stats/:year/:month

Get host statistics for the specified month.

$ curl https://pageload.io/api/1/hosts/1/stats/2013/09 \
    -u acZsjXjAHh9aLXKhl4gxSxhhhw9Mj3xm:

GET /api/1/hosts/1/daily-stats/:year/:month

Get host statistics for the specified month, broken down by day.

$ curl https://pageload.io/api/1/hosts/1/daily-stats/2013/09 \
    -u acZsjXjAHh9aLXKhl4gxSxhhhw9Mj3xm: