CacheFly API (2.4.3 beta)

API tokens are intended to be used for automated user not present integrations, that is where requesting interactive authentication would not be possible/desirable.

Users may create API tokens (if they have permissions to do so). The created token may have the same set of permissions and services as the user that created it, or any subset thereof. Users are not permitted to create tokens which have more permissions than themselves.

API tokens do not expire, and are only returned from the API once. After the API token has been created it's permissions may be modified, which allows for granting additional permissions to an application without needing to reconfigure it.

Logging in is intended to be used only when the user is present and actively interacting with the application. Logging in issues a new temporary API token which shares the same permission set as the authenticated user. The token should be discarded when the interactive session ends.

As the token is temporary it has an expiry date which is enforced by the API. The validity time for the token is typically one hour, but may be shorter. If needed the token can be renewed by exchanging it for a new temporary token.

See API Tokens for tokens which are to be used when the user is not present.

The Account Recovery endpoints allows a user to recover access to their account when they have forgotten their authentication credentials.

A CacheFly account is a representation of the entity who will be invoiced for provided services. All other API objects are contained within an account either directly or indirectly.

It is expected that most companies will need only one account. The concept of sub accounts found in the older version 1 API has been directly replaced by the concept of services. Opening multiple accounts is only required to separate invoicing concerns.

Accounts may contain multiple services which can be organised and configured according to your own needs. Each service provides an aggregation point for configuration, logging, statistics, etc.

It is reasonable to think of a service as being similar to the virtual host concept from a typical web server configuration.

When applying changes to a service there may, or may not, be a propagation delay. This is to ensure that a high frequency of changes by a small number of users does not negatively impact the performance of the network as a whole. As such, although we endeavour to make this as fast as possible, and immediate in most cases, the only guarantee is that it will occur eventually.

Service configurationMode enumeration that defines which type of configuration is going to be applied, it can be changed on upon request per service. Following configuration modes are available:

• API_OPTIONS - Simple set of configuration parameters, more details are available in Service Options section.
• API_RULES - Service rules offer more advanced configuration, more details are available in Service Rules section.
• API_RULES_AND_OPTIONS - Use service rules as main configuration set and service options as fallback.
• MANUAL - Custom configuration available upon request.

Note that in failure scenarios we will continue to serve traffic using the last working configuration.

Each service has a set of domains. Depending on available features, one or more defaults will be added to the service when it is created, including <uniqueName>.cachefly.net.

Adding a domain to a service will configure the CacheFly edge servers to route all traffic received for that name through the configuration for that service. Each domain name must be a fully qualified hostname. If you wish to serve traffic for both www.example.com and example.com then you will need to add both names.

Once created domains are automatically related to TLS certificates if there are any that matches the name. You do not need to maintain the relationship between domains and certificates.

Please note that the propagation delay mentioned in the description of a service also applies to service domains.

You should configure the DNS for your custom domains to alias one of the default service domain names that you are given.

A time to live (TTL) of 86400 seconds (24 hours) is recommended to gain a performance advantage from shared DNS caching. Note that setting your TTL lower than 2400 seconds (1 hour) is suboptimal for performance.

DNS Example:

www.example.com.    IN    86400    CNAME    <uniqueName>.cachefly.net

You should never place a CacheFly IP address in your DNS configuration as that prevents us from applying early geographic performance optimisations, and may prevent us from ensuring continued uptime during maintenance or unscheduled outages.

If you are unable to use a CNAME, you should look into using provider specific equivalents (e.g. ANAME, ALIAS, RECORD LINKING, etc).

Each service has a set of rules. Rules define how the service should behave when serving traffic.

Please note that the propagation delay mentioned in the description of a service also applies to service rules.

How rules work

Each service contains a list of rules. Each rule contains a list of conditions and a list of actions.

When handling a request for one of the configured service domains each rule is considered in order. If all of the conditions for that rule are true, then the actions on that rule are performed. If they are not true then the next rule in the list is considered.

Incomplete example (YAML format): ```yaml

• conditions: [] # Rule 1 actions: []
• conditions: [] # Rule 2 actions: []

By convention the list of rules is written in YAML format when it is presented for humans to read, and in JSON format for machines/software to read. For comparison here is the above example in JSON format.


Incomplete example (JSON format):
```json
[
  { "conditions": [], "actions": [] },
  { "conditions": [], "actions": [] }
]

Branches

Special attention should be given to the BRANCH action which contains within itself a rules list. When the conditions guarding this action are true processing moves into the rules list that it contains. This allows for the configuration of a rules in a tree like structure.

Example (YAML format): ```yaml

• conditions: [] # Rule 1 actions:
  • type: BRANCH terminal: false rules:
    • conditions: [] # Nested Rule 1.1 actions: []
    • conditions: [] # Nested Rule 1.2 actions: []
• conditions: [] # Rule 2 actions: []

By convention the list of rules is written in YAML format when it is presented for humans to read, and in JSON format for machines/software to read. For comparison here is the above example in JSON format.


Incomplete example (JSON format):
```json
[
  { "conditions": [], "actions": [] },
  {
    "type": "BRANCH",
    "terminal": false,
    "rules": [
      { "conditions": [], "actions": [] },
      { "conditions": [], "actions": [] }
    ]
  },
  { "conditions": [], "actions": [] }
]

Conditions allow you to specify when a list of actions should be taken, or not. Please refer to the list service rules examples for a definition of the properties available for each condition.

Many more conditions are planned for addition during and after beta.

Actions describe what is possible to do when a list of conditions is met. Please refer to the list service rules examples for a definition of the properties available for each action.

Many more actions are planned for addition during and after beta.

The following actions are reserved for internal use only, they may be visible to you in a rules list if added by the CacheFly engineering team.

During beta, restrictions may change prior to those changes being documented. Please pay attention to the text of the API error messages.

Service rules are flexible by design. This has resulted in the possibility of combinations of configurations which are illogical or impractical. As such the API applies restrictions to the rules list to reduce the changes of it being rejected by the backend systems. You should always endeavour to comply with these restrictions when generating a rules list.

• The actions list on a rule must not be empty.
• The rules list on a BRANCH action must not be empty.
• No action may follow an action which has the terminal property.
• Must not mix multiple PATH condition modes in a single rule.
• The PATH condition mode EXACT prohibits any other PATH condition within any nested rule.
• The PATH condition mode REGEX requires that any other PATH condition within any nested rule is of the same mode.
• The PATH condition mode PREFIX requires that any other PATH condition within any nested rule starts with its prefix value.

For clarity conditions list on a rule is permitted to be empty.

Service options represents a simple way to configure a service comparing to service rules. Service options are available if the service configurationMode enumeration is set to API_OPTIONS or API_RULES_AND_OPTIONS, which can be enabled on request per service or as default configuration for an account.

For objects which have been cached by a reverse proxy configuration, purge allows you to invalidate the cache and instructs the us to attempt to fetch an updated copy of the object from the origin. The fetch will occur the next time that the object is requested. Please note that if the origin is unavailable an error is served (not stale/invalidated objects).

You can specify a list of paths which are to be purged. These can be complete paths (e.g. /images/backgrounds/sky.jpg), or they can be the path to a directory (e.g. /images/backgrounds/). Directory paths must end with a forward slash. When a directory is specified all objects within that directory are purged.

Alternatively you can request that all of the objects cached for a service are purged. If you have a large number of objects you should avoid purging all of the objects in one go like this, as it may overload your origin.

When purging a list of paths, the paths field is required and the all field should be absent (or set to false).

When purging all objects, the all field must be set to true and the paths field should be absent. Please note that the all field overrides the paths field, so setting it to true will always purge all objects regardless of what is placed in the paths field.

TLS / SSL Certificates are stored within an account, and are not specific to an any one service. Certificates will be automatically configured to any/all relevant services from the same account, based on service domains.

Certificates managed by the user can be uploaded and deleted. Certificates managed by CacheFly can only be viewed. Please contact sales to purchase managed TLS certificates.

Uploaded keys are stored encrypted and are not available for retrieval and distribution outside of our internal network. If you need to retrieve your keys from us please contact our support team to discuss your requirements.

Origin objects are the representation of origin of your content. Origins become associated to services via the use of rules which instruct the service to reverse proxy traffic to a specific origin.

Origins are typically either your own server, a cloud server, or a cloud storage solution. These can all be configured via this API by setting the appropriate hostname for the HTTP interface of the origin.

Other types of origins are also available on request, such as CacheFly provided storage solutions, or CacheFly managed edge application servers.