Key concepts and terms

There are a few basic concepts you should know before you begin setting up your properties. Here we provide a road map of all the terms you deal with when interacting with the Property Manager application.

How users access your content

To understand the content delivery flow better, here are a few definitions you want to keep straight:

  • Domain Name Server (DNS). Keeps track of domain names and translates them to an IP address.

  • DNS CNAME. A record that specifies that a domain is an alias for another domain. Configure your DNS server so that requests for each domain resolve to a corresponding edge hostname, the latter referred to as the canonical name. In turn, servers across the ​Akamai​ network use their own CNAME records to resolve these edge hostnames to more specific local server names and ultimately their IP addresses.

  • Origin server. This is the server where you maintain your content for deliveryyour website assets, streaming media files, downloadables, etc. ​Akamai​ edge servers will regularly ping your origin server to get the most up-to-date content to hold it in cache for quicker delivery.

  • Origin hostname. A new DNS record that points to your origin server. You create this DNS record (for example, {origin}-www.example.com). See Custom origin prerequisites and Types of hostnames for more details.

  • Edge server. The ​Akamai​ network server.

  • Edge hostname. The DNS record that points to the most optimal ​Akamai​ edge server. We provide this (for example, www.example.com.edgesuite.net). See Types of hostnames for more details.

How content delivery works

When users visit your site, their browsers do a DNS lookup of your domain name. Without ​Akamai​, your DNS configuration returns an A or AAAA record that points to your origin server.

To serve your traffic through ​Akamai​, you need to direct end users to an ​Akamai​ server. First, you change the DNS configuration for your domain. Instead of an A record, you need a CNAME record that redirects the DNS request to the edge hostname. Once the CNAME record is in place, ​Akamai​ DNS servers return the IP address of the best ​Akamai​ servers for the user's request. The browser uses the ​Akamai​ IP addresses to retrieve content from your site. If necessary, the ​Akamai​ servers will look up your origin hostname to connect to your origin server to retrieve content.

Types of hostnames

There are three types of hostnames involved in serving your content through ​Akamai​:

  • Origin server hostname. A label you define for your physical server when you first establish it and connect to a computer network. Today your end users reach your origin server using your primary domain. After you go live on ​Akamai​, your primary domain will point to the edge servers, so you need to create a new hostname for your origin (for example, origin-www.example.com). This new name will appear in the origin DNS record and tell our edge servers from where they can retrieve content to serve over the ​Akamai​ network.

  • Property hostname. The name of your site or application that your users access by clicking a link or typing a URL in their browser, without the "http(s)://". Property hostnames are fully qualified domain names (FQDN) that consist of a subdomain indicating a property type (such as www, mfor mobile, imgfor images, shopfor an online store, and so on), and your main hostname (such as example.com). When you set up your property, you associate its hostname with an edge one. This way, the requests for your content are redirected to ​Akamai​ edge servers. The property hostname helps the edge network determine that the request belongs to you as our customer and apply a dedicated configuration file. A hostname plays two roles:

    • As an address: used to locate a server that can serve the site's content.

    • As a Host HTTP Header: used to tell the server which site the request is asking for. It is entirely possible for multiple sites to be served by the same server.

  • Edge hostname. A CNAME target. That means, if your user requests a property hostname of www.example.com, their request is rerouted to ​Akamai​ edge hostname, for example, www.example.com.edgekey.net. This essentially gets your property onto the ​Akamai​ network. Once the DNS for a site points to an edge hostname, ​Akamai​'s mapping algorithms determine the IP address of the most optimal edge server. The edge server then accesses the property configuration file to deliver the content according to the rules you set. For example, how long to cache certain objects or what cookie type to send with the response to the client.

    Your edge hostname settings may vary depending on the level of security you need for your traffic.

Usually, property hostnames are configurable from the level of property version, which means that every change to the property hostnames increments the property version and requires a separate activation. If you manage thousands of custom domains and can't use wildcard property hostnames and certificates, the most efficient solution is to create a property with a hostname bucket. Hostname buckets let you add or remove thousands of property hostnames and automatically activate the changes without affecting the property versions. You can safely make updates to the configuration logic and roll them back without the risk of accidentally removing hostnames and disturbing the traffic to your sites. Hostname buckets are primarily intended for SaaS/PaaS providers who need one common set of rules applied to tens of thousands of custom domains.

Content structure

You might want to use ​Akamai​ products with multiple digital assets. To ensure it's easy to manage them all, ​Akamai​ has developed a special content structure.

The list starts with the largest entity that is further subdivided into smaller content elements:

  • Accounts. You can access all your services with an account key. While administrators may have access to more than one account, in general, they provision all their web assets under a single account within ​Akamai Control Center​. Accounts can comprise several groups.

  • Groups. Each account features a hierarchy of groups, which control access to properties and help consolidate reporting functions, typically mapping to an organizational structure. During creation of a property, an account administrator assigns the property to a specific group. Each group has its own set of users and accompanying roles. Your access to any given property depends on the role set for you in its group.

  • Contracts. Each account features one or more contracts, each of which has a fixed term of service during which specified ​Akamai​ products and modules are active.

  • Products. Each contract enables one or more products, each of which allows you to deploy web properties on the ​Akamai​ edge network and receive associated support from ​Akamai​ Professional Services. Products allow you to create new properties, CP codes, and edge hostnames. They also determine the baseline set of a property's rule behaviors.

  • Modules. Modules are add-ons to products that may enable additional rule behaviors. Different products support different sets of modules. Your ability to specify any given rule behavior depends on the currently active product and associated modules.
    API only: PAPI doesn't provide information directly about your selected modules, but it does allow you to determine the currently available behaviors and criteria they enable.

  • Properties. A property is the most granular object in the hierarchy and the first step on your journey to deliver your content over ​Akamai​. You can think of a property as a container for your ​Akamai​ setup and services for your site, application, download files, or streams.

Properties

The edge network caches your web assets near to servers that request them. A property, sometimes also referred to as a configuration, provides the main way to control how edge servers respond to various kinds of requests for those assets. Properties apply rules to a set of hostnames, and you can only apply one property at a time to any given hostname. Each property is assigned to a product, which determines which rule behaviors you can use.

Let's clear up the concepts you should be familiar with while editing properties:

  • Versions. Each property has snapshot versions, which allow you to modify one instance of a property while another is activated. You can freely modify a property version, along with its component hostnames and rules, up until you activate it. Following activation, you need to create a new version to modify it further. You don't need to create a new property version for each modification you make. Versions use an ascending number as an ID. They also feature a timestamp, the username of the person who last modified it, and some notes.

  • Activations. Once you're satisfied with any version of a property, an activation deploys it, either to the ​Akamai​ staging or production network. You activate a specific version, but the same version can be activated separately more than once. You can either cancel an activation shortly after requesting it, or in many cases, use a fast fallback feature within a matter of seconds to roll back a live activation to the previously activated version.

  • Metadata. Once activated, the property settings are distributed to the ​Akamai​ network as an XML configuration file, also known as metadata. This low-level XML format combines information about the property's rules and hostnames.

  • Errors and warnings. When you modify different aspects of a property, errors or warnings may pop up along the way. An error prevents you from activating a property version, but you can activate versions that yield less severe warnings. You may need to acknowledge each warning when you activate a version, but there's an option to skip them.

Includes

Includes are snippets of a property configuration that let you reuse common settings in different properties or delegate the management of a portion of business rules to responsible application teams. Includes are similar to regular properties, also referred to as “parent” properties, but don't have hostnames assigned to them. You can also version and activate includes independently of the properties that use them. See Includes for more details.

Configuration elements

Rules, matches, and behaviors are the heart of your property configuration. These elements let you decide how your content is delivered to the end users.

  • Rules. Properties allow you to design rules to respond to different kinds of requests. A rule consists of behaviors and optionally a set of match criteria. In addition to a top-level default rule that determines overall behavior, you may include any number of your own rules, arranged in a tree structure up to five levels deep. You can control the order in which they apply and create parent-child relationships between rules.
    API only: PAPI provides an interface to the entire rule tree, not to each component rule.

    See Rules for more details.

  • Rule templates. A template is a predefined rule that you can insert into your configuration as-is or modify to a slight extent. Rule templates also group together commonly used functionalities so that they are easy to find.
    API only: PAPI doesn't support the rule templates feature available in the Property Manager interface, since programming tools allow you to build your own rule templating system more flexibly.

  • Rule formats. ​Akamai​ often modifies behaviors and matches, each time deploying a new internal version of the feature. By default, the Property Manager interface in ​​Control Center​ uses the latest available feature versions, but you can select another rule format while creating a new property or editing a property version. In the interest of stability, some Property Manager solutions like includes or API don't support this system of selective updates for each feature. Instead, the feature sets are simply versioned as a whole. These versions, which update infrequently, are known as rule formats.

    See Rule formats for more details.

  • Matches. Match criteria are the conditions that help you to define when a behavior should be applied. They are the IFs in your configuration, for example, "If there's an origin failure like a timeout...".

    See Matches for more details.

  • Behaviors. Also referred to as features, behaviors instruct the edge servers how to manage requests. They are the THENs in your configuration, for example, "... redirect user requests to an alternate hostname".

    See Behaviors for more details.

  • Advanced and custom behaviors. Most behaviors translate to edge metadata in clearly prescribed ways. Functionality that falls outside what these predefined behaviors and criteria can do may be implemented as advanced metadata.

    Custom behaviors let you easily reuse advanced metadata in Property Manager configurations across your account.

    📘

    Advanced and custom features

    When implementing advanced and custom features, reach out to ​Akamai​ Professional Services to configure them for you.

  • Variables. Many behavior and criteria values allow you to add a variable text that interprets at runtime on edge servers, typically based on details about the client request.

    See Variable overview for more details.

  • CP codes. You need a content provider (CP) code to track any web traffic handled by ​Akamai​ servers. ​Akamai​ provides a CP code when you purchase a product, and you need it to activate any associated properties. You can generate additional CP codes, typically to implement more detailed billing and reporting functions, and to assign to customized properties. Each property requires at least one CP code behavior as part of its default rule.

  • API only: Schemas. Some errors may result when a request isn't in the expected format. In that case, errors reference request schemas that represent the expected structure formatted as a JSON Schema object.

  • API only: Rule formats. Akamai often modifies PAPI features, each time deploying a new internal version of the feature. By default, the Property Manager interface in Control Center uses the latest available feature versions and you may be prompted to upgrade your configuration. In the interest of stability, PAPI does not support this system of selective updates for each feature. Instead, PAPI's rule objects are simply versioned as a whole. These versions, which update infrequently, are known as rule formats.

    You use rule formats to freeze or update the versioned set of behaviors and criteria a rule tree invokes. PAPI users should assign the most recent dated rule format to freeze the set of features. Otherwise, if you assign the latest rule format, features update automatically to their most recent version. This may abruptly result in errors if JSON objects your rules specify no longer comply with the most recent feature's set of requirements. PAPI provides a more stable path to update rule formats that fixes these requirements for you.

    PAPI tracks rule formats in a database keyed by rule format version date strings. These reference rule format schema objects, which specify the full set of behaviors and criteria available for a given product and the set of modules it may enable, as well as their allowed options and option values.

  • API only: Client settings. This API resource collects various configuration parameters for clients keyed to an authorization token.

API Only: Bulk operations

PAPI supports a set bulk operations to manage many properties' rule trees at once. See the Bulk Search and Update section for details on this feature.

  • Bulk searches. Bulk searches use a flexible JSON path-based query syntax to search across all your activated property versions' rule trees. After your search request, search results become available asynchronously for all matching property versions. They include JSON path expressions that locate all the rule tree behaviors and criteria you searched on, for use in a subsequent bulk patch operation.

  • Bulk versions. You feed the results of a bulk search into another operation that creates new versions for the entire set of properties. This new set of versions becomes available asynchronously.

  • Bulk patches. In a bulk patch operation, you use the JSON path locators in conjunction with JSON Patch operators to form a set of customized instructions to modify each property's rule tree. The results become available asynchronously.

  • Bulk activations. After batch-updating a set of properties, you can asynchronously bulk activate them to the staging or production network.