HapYak supports 3rd party content delivery networks (CDN’s) to enhance the performance of serving both static assets, and API requests.
Enabled / Disabled
The enabled parameter allows the partner to turn off the API CDN temporarily. This can be used to enable "real time" viewer/editor requests. A good practice is to disable the API CDN for the owner/editor of the video so they can see real time previews, but enable it for all other viewers of the video.
CDN Setup and Requirements
HapYak requires the following features to be supported by 3rd party CDN's.
Forward all asset requests to:
- Query parameters support: HapYak uses query parameters on asset urls to cache bust when new releases are deployed. For example, v=566 is appended to all CSS URL's. When we deploy a new release, v=567 will be appended to those URLs. The expectation is that this will result in a cache miss in the CDN, and the request will be forwarded to HapYak.
- Cache-Control: Cache-Control headers are used to specify expiration directives. For example, Cache-Control: max-age=600. The hapyak.js script, which loads all other scripts is set to cache for 10 minutes, the other scripts are set to cache for 30 days. When HapYak deploys a new revision, a new hapyak.js loader is deployed with a new version number embedded. 10 minutes later, the user gets the new version, and all additional asset requests will include a new v=# parameter, resulting in updated assets.
- Last-Modified / ETag / If-Modified-Since: The HapYak CDN will include Last-Modified, and ETag headers in the response. Requests to the HapYak CDN should include Last-Modified, and ideally If-Match request headers to avoid transferring assets unnecessarily.
Forward all API requests to:
- Query parameters support: API CDN requests are required to support caching with query parameters. The HapYak API endpoints utilize a number of query parameters.
- Cache-Control: The default max-age directive returned from HapYak is 60 seconds. Cache-Control: max-age=60.
- Last-Modified / If-Modified-Since: It is critical for scalability to support these headers in the CDN. HapYak will return the Last-Modified date for the track. After 60 seconds, a new request to the HapYak API with If-Modified-Since should be triggered. HapYak very quickly compares dates, and will respond with an HTTP 304 if nothing has changed. The 304 response will also include Cache-Control, letting the CDN know it can cache that response for another 60 seconds.
- Content-Encoding: HapYak API responses may be encoded using Gzip. If Accept-Encoding: gzip is included in the HTTP request, HapYak will return a GZip response with Content-Encoding: gzip. The CDN should either have the ability to cache both versions, gzip and not gzip, depending on if the end users browser passed Accept-Encoding, or should not pass Accept-Encoding along to HapYak.
- SSL: Please forward requests to HapYak from your CDN without SSL, even if the original request was SSL enabled.
Most existing CDN's support these features. The CDN capability was designed using Amazon Cloudfront as a reference.
Forcing API Cache Timeout
If 60 seconds is too long to wait for API changes, you can append a cache busting query parameter to the CDN prefix. A best practice would be to use some piece of local knowledge to bust the cache. For example, if you know the last time the user clicked the "Edit Annotations" button, that time could then always be appended to the CDN prefix.