API concepts

To understand this API's various URL resources and the data it exchanges, you need to familiarize yourself with these concepts:

Identity: Each account has high-level information about the API client, the Akamai user that it's linked to, and contracts available to the client. Each contract lists available load balancing features, and the permissions the client has on the domains tied to the contract.
Contract: Each account has one or more contracts with a fixed term of service that specifies the active Akamai products and modules. Along with information about the group, you may need the contractId to create a new domain.
Group: Each account has a hierarchy of groups that control access to domains and help to consolidate reporting functions that typically map to an organizational hierarchy. Each group lists the GTM contracts that the group has access to, and the set of permissions the API client has on the group such as READ, WRITE, ADD, and ADD_DATACENTER.

With either Control Center or the Identity and Access Management API, account administrators can assign GTM domains to specific groups, each with its own set of users and accompanying roles. Your access to any given domain depends on the role set for you in its group. Along with information about the contract, you may need the groupId to create a new domain.

The Identity and Access Management application lets you limit the groups a client has access to. If you are able to limit access to a single group, one linked with only one contract, then the client doesn't need the groupId or contractId when creating domains.
Domain: The basic building block of a traffic management configuration is a domain. The DNS defines a tree-structured namespace. For example, in this list, each item is a domain and each domain is a subdomain of the previous item in the list:
- com
- customer.com
- sales.customer.com
Akamai's GTM system uses the term domain in a slightly restricted sense. A GTM domain is a DNS domain, whose name usually ends in .akadns.net. Several important attributes exist at the GTM domain level such as access control. Anyone with permission to edit a GTM domain has permission to modify or delete any of the subdomains within that domain.

A GTM domain has one or more subdomains that share a number of domain-wide attributes. These attributes include use of load feedback, load imbalance factor, the set of available data centers, and so forth. Each domain object is a representation of a complete GTM domain, such as example.akadns.net. Your contract determines the set of GTM domain types available to you.
Property: A set of IP addresses or CNAMEs that GTM provides in response to DNS queries based on a set of rules. In GTM, properties are subdomains, and don't relate to Property Manager and PAPI. A GTM property type specifies the load balancing behavior for the property. For example, www, which in DNS terms is a subdomain of the domain, combined with its domain example.akadns.net, the fully qualified domain name www.example.akadns.net used for load balancing.
Liveness Test: Configure GTM to perform liveness tests periodically to determine whether your servers respond to requests. When you do this, GTM tries to return answers that contain only the A records for live servers. Systems called liveness testing agents, also known as servermonitors, perform liveness tests. GTM allocates a set of seven agents for each of your data centers, chosen for proximity to your data center and for network diversity. Many agents conduct liveness tests to avoid the possibility of an ISP falsely declaring your data center down due to local network issues. If all servers for a property fail their liveness tests, GTM considers all the servers up, as it has no basis to prefer any of them. When any server in a data center is up, GTM considers the data center up.
Data center: Represents a customer data center, also known as a traffic target, which is a location that contains many servers to which GTM directs traffic. More generally, a data center is a name for a set of possible answers that GTM can return for a query and the unit GTM uses to scale load balancing. For example, you might have data centers in New York and in Amsterdam, and want to balance load between them, but prefer that U.S. users are sent to the New York data center and European users are sent to the Amsterdam data center.
Data center affinity: A mechanism that helps reduce, but not eliminate, reassignment of your end users from one data center to another. GTM attempts to map users to the data center where they have the best connectivity to improve performance for them. However, if a user is roughly the same distance from two data centers, making their scores similar, small variations in scores might cause GTM's choice of the best data center to vary. Thus, GTM frequently reassigns the user to these two data centers. Data center affinity lets you determine when user reassignment occurs for the best connectivity and performance.

Two property object members control data center affinity, stickinessBonusPercentage and stickinessBonusConstant. The stickinessBonusPercentage is a percentage of a data center's score and stickinessBonusConstant is an absolute number. For example, if the stickinessBonusPercentage is 10, users are reassigned when a data center's score is at least 10% better than the current data center. Similarly, when the stickinessBonusConstant is 100, users are reassigned when a data center's score is 100 milliseconds better than the current data center.
CidrMap: Classless Inter-Domain Routing (CIDR) mapping uses the IP addresses of the requesting name server to provide IP-specific CNAME entries, which lets you direct internal users to a specific environment or direct to the origin. This provides different responses to an internal corporate DNS infrastructure such as internal test environments and another answer for all other defaultDatacenter name servers. CIDR maps split the Internet into multiple CIDR block zones. Properties that use a map can specify a handout CNAME for each zone on the property's editing page. To configure a property for CIDR mapping, your domain needs at least one CIDR map defined.
AsMap: Autonomous System (AS) mapping lets you configure a property that returns a CNAME based on the AS number of the IP address of the requester. You can reuse maps for multiple properties or create new ones. AS maps split the Internet into multiple AS block zones. Properties that use AS maps can specify handout integers for each zone. AS mapping lets you configure a property that directs users to a specific environment or to the origin.
GeographicMap: Geographic mapping lets you configure a property that returns a CNAME based on the geographic location of the request. You can reuse maps for multiple properties or create new ones. To configure a property for geographic mapping, your domain needs at least one geographic map defined. Each map needs at least two definitions. This ensures that at least one definition maps one or more countries to a data center, and the second definition routes all other traffic.
Resource: Represents a constraint on how much load a data center can absorb. Consider a resource as something that can impose a capacity constraint on the load associated with one or more properties in a data center. Examples of resources include: bandwidth, CPU load average, database queries per second, or disk operations per second.

Resources contain the architecture and topology of the network in a data center. For example, each property has a resource that represents the capacity of the servers for that property. In addition, there might be a resource that constrains the aggregate bandwidth available to all properties in a data center. As an example, for a database application, you might decide that the most important measurement of load is queries per second. For a static web server, you might choose to measure HTTP GET requests per second. A resource is a name for something that you measure that reflects how you want to balance load across your data centers. You report the load in whatever units make sense to you. To GTM, loads are unit-less quantities.

A resource constrains a property if it's affected or consumed by load on that property. You can configure a resource to constrain one or all properties. Resources can constrain multiple properties if you are using XML load objects. With non-XML load objects, or with download score based load balancing, resources and properties correspond to each other on a one-to-one basis. For example, you may decide that you need to balance your use of Internet bandwidth. Since all Internet traffic consumes bandwidth, configure your bandwidth resource to constrain your properties.
Status: Specifies the current condition of the change in the domain's activation.
UpdateResponse: A common object wrapper that reflects back the data that you updated, and tracks the update's status.
Hypermedia: The API's data objects feature embedded link relations that provide URL paths that allow direct navigation to each object. For example, when you List domains, items within the list include link relations where the href link relation responds to a GET request for a specific GTM domain and the rel link relation self indicates that is the link you need to GET for that specific object, as shown here.

"links": [
        {
            "href": "/config-gtm/v1/domains/example.akadns.net",
            "rel": "self"
        }
    ],