Contract API v1

A microservice that provides Akamai contract identifiers and associated products to other APIs.

Learn more:


Overview

The Contracts API provides information about Akamai contracts as well as the products included in those contracts. With this API, you have the option of retrieving product information for a specified time frame by either contract ID or reporting group.

NOTE: This API is currently in beta.

Who should use this API

Developers who need information about their organization’s Akamai contracts and the products associated with those contracts should use this API.

Contracts are important low-level objects on which other services depend. For example, you can use them in conjunction with the Billing Center or Invoicing APIs.

Getting started

To get started with this API:

  • Review Get Started for a general overview on the tasks you need to complete before using this API.

  • Go to the Akamai’s GitHub page and find the name of the EdgeGrid project for the language you are using. Most file names follow this format: AkamaiOPEN-edgegrid-_language_, like AkamaiOPEN-edgegrid-java.

  • In the Luna Control Center, authorize your client and download your credentials using the Manage APIs application. See Authorize Your Client for more information.

  • Configure your EdgeGrid client using your downloaded credentials. See Configure Your Client for more information and a Python example.

  • Test your configuration by running the List Contract IDs operation.

  • If using the Content Provider (CP) Code Reporting Group operations, your user account needs the CPCode Rep Group role. To add this role, use the Manage Users and Groups application. You also have the option adding this role programmatically with the User Admin API.

Concepts

The Contracts API provides information about Akamai contracts as well as the products included in those contracts. With this API, you have the option of retrieving product information by contract ID or reporting group ID for a specified time frame.

Contracts and reporting groups are important low-level objects on which other services depend. For example, you can use them in conjunction with the Billing Center or Invoicing APIs.

  • Contracts: When using this API, your level of access depends on the contracts your Luna Control Center username is associated with. If your username is not associated with the contractId you select, then the request fails. To understand contracts, you need to understand how accounts work at Akamai. Akamai customers access all their services via 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 an account, there are one or more contracts, each of which has a fixed term of service during which specified Akamai products and optional modules are active.

  • Child Contracts: A contract may include one or more child contracts (or subcontracts) that belong to the same account. If you get a contract that has child contracts, it will only list the products included on the parent contract. The API does not indicate the relationship between contracts. To retrieve only the products for the child contract, perform a GET on the child contract’s ID.

  • Reporting Groups: A reporting group is a logical grouping of multiple content provider (CP) codes that consolidates reporting for a contract. When using this API to retrieve information by reporting group, the request will fail if your username is not associated with the contract that the reporting group supports. In addition, your user account needs to include the CPCode Rep Group role in order to run the reporting group operations. Reporting groups are provisioned by Akamai. To request reporting groups or get more information, open a ticket under ‘Support’ on Luna Control Center or contact your account representative.

  • Content Provider (CP) Code: A content provider is an Akamai customer that serves traffic on the Akamai network. A CP code is a unique identifier assigned to each customer, used primarily for billing, reporting, and access control. A customer and a single contract may each have multiple CP codes.

Resources

The Contracts API provides information about Akamai contracts as well as the products included in those contracts. With this API, you have the option of retrieving product information for a specified time frame by either contract ID (contractId) or reporting group (reportingGroupId).

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Contracts  
List Contracts GET /contract-api/v1/contracts/identifiers{?depth}
List Products per Contract GET /contract-api/v1/contracts/{contractId}/products/summaries{?from,to}
Reporting Groups  
List CP Code Reporting Groups GET /contract-api/v1/reportingGroups/
List CP Code Reporting Group IDs GET /contract-api/v1/reportingGroups/identifiers
List Products per Reporting Group GET /contract-api/v1/reportingGroups/{reportingGroupId}/products/summaries{?from,to}

List contracts

Get the list of contracts that a user has access to.

GET /contract-api/v1/contracts/identifiers{?depth}

Sample: /contract-api/v1/contracts/identifiers?depth=TOP

Parameter Type Sample Description
Optional query parameters
depth Enumeration TOP Returns a specific set of contracts. Select TOP to return only parent contracts or ALL to return both parent and child contracts.

Status 200 application/json

Response Body:

[
    "1-3CV382",
    "1-6T5ZND"
]

List products per contract

Get the IDs and names of the products associated with a contract for the time frame selected.

GET /contract-api/v1/contracts/{contractId}/products/summaries{?from,to}

Sample: /contract-api/v1/contracts/2-4DW493/products/summaries?from=2015-01-31&to=2016-03-31

Parameter Type Sample Description
URL parameters
contractId String 2-4DW493 The unique identifier for a contract.
Optional query parameters
from String 2015-01-31 The start date, in UTC, to use when looking for products associated with a contract. The search always begins at midnight (0:00) UTC of the specified date. The default start date is 30 days prior to the current date. For current contracts, you can select a date within the past 15 months of the current date. For expired contracts, you are limited to a date range of 30 days within the 15 month window.
to String 2016-03-31 The end date, in UTC, to use when looking for products associated with a contract. The search always ends at 23:59:59 UTC of the specified date. The default end date is the current date.

Status 200 application/json

Response Body:

{
    "products": {
        "contractId": "1-2RBL",
        "marketing-products": [
            {
                "marketingProductId": "B-3-96NY56",
                "marketingProductName": "Access Control - All Streaming Delivery"
            },
            {
                "marketingProductId": "B-3-A5ME5",
                "marketingProductName": "Site and Visitor Intelligence"
            },
            {
                "marketingProductId": "B-4-1O78TS",
                "marketingProductName": "All Streaming Delivery"
            }
        ]
    }
}
  1. Run the List Contracts operation and store the value as contractId.

  2. Optionally, set the earliest time from which you want to list records.

  3. Optionally, set the latest time to which you want to list records.

  4. Make a GET request to /contract-api/v1/contracts/{contractId}/products/summaries{?from,to}.

List CP code reporting groups

Get the IDs of the Content Provider (CP) reporting groups that you have access to along with their names. To run this operation, your user account needs the CPCode Rep Group role. To add this role, use the Manage Users and Groups application.

GET /contract-api/v1/reportingGroups/

Status 200 application/json

Response Body:

[
    {
        "id": 12289,
        "name": "foo.com group"
    },
    {
        "id": 139267,
        "name": "*.example.com"
    },
    {
        "id": 139268,
        "name": "images traffic group"
    },
    {
        "id": 7182,
        "name": "www.bar.com"
    },
    {
        "id": 13844,
        "name": "Radio and Streaming"
    },
    {
        "id": 130221,
        "name": "All Mini Country sites"
    }
]

List CP code reporting group IDs

Get the IDs of the Content Provider (CP) reporting groups that you have access to. To run this operation, your user account needs the CPCode Rep Group role. To add this role, use the Manage Users and Groups application.

GET /contract-api/v1/reportingGroups/identifiers

Status 200 application/json

Response Body:

[
    503,
    999,
    201
]

List products per reporting group

Get the IDs and names of the products associated with the reporting group for the time frame selected. To run this operation, your user account needs the CPCode Rep Group role. To add this role, use the Manage Users and Groups application. When a request is successful, it may return either a 200 or a 300 response. The API returns a 200 (OK) response when the CP code reporting group is associated with only one contract. You’ll receive a 300 (Multiple Choices) response when the request returns a list of matching contracts because the CP code reporting group is associated with multiple contracts. To retrieve product information when you receive a 300 response code, make a new GET request to the hyperlinks provided in the response.

GET /contract-api/v1/reportingGroups/{reportingGroupId}/products/summaries{?from,to}

Sample: /contract-api/v1/reportingGroups/1001/products/summaries?from=2015-01-31&to=2016-03-31

Parameter Type Sample Description
URL parameters
reportingGroupId Number 1001 The unique identifier for a Content Provider (CP) code reporting group.
Optional query parameters
from String 2015-01-31 The start date, in UTC, to use when looking for products associated with a contract. The search always begins at midnight (0:00) UTC of the specified date. The default start date is 30 days prior to the current date. For current contracts, you can select a date within the past 15 months of the current date. For expired contracts, you are limited to a date range of 30 days within the 15 month window.
to String 2016-03-31 The end date, in UTC, to use when looking for products associated with a contract. The search always ends at 23:59:59 UTC of the specified date. The default end date is the current date.

Status 200 application/json

Response Body:

{
    "products": {
        "contractId": "1-2RBL",
        "marketing-products": [
            {
                "marketingProductId": "B-3-96NY56",
                "marketingProductName": "Access Control - All Streaming Delivery"
            },
            {
                "marketingProductId": "B-3-A5ME5",
                "marketingProductName": "Site and Visitor Intelligence"
            },
            {
                "marketingProductId": "B-4-1O78TS",
                "marketingProductName": "All Streaming Delivery"
            }
        ]
    }
}

Status 300 application/json

Response Body:

{
    "contracts": [
        {
            "contractId": "3-ZQ0H6H",
            "href": "/contract-api/v1/contracts/3-ZQ0H6H/products/summaries"
        },
        {
            "contractId": "3-1EBV5F",
            "href": "/contract-api/v1/contracts/3-1EBV5F/products/summaries"
        },
        {
            "contractId": "3-XC1A0F",
            "href": "/contract-api/v1/contracts/3-XC1A0F/products/summaries"
        }
    ]
}
  1. If your user account needs the CPCode Rep Group role, use the Manage Users and Groups application to add it.

  2. Run the List CP Code Reporting Group IDs operation and store the reportingGroupId.

  3. Store the reportingGroupId.

  4. Optionally, set the earliest time from which you want to list records.

  5. Optionally, set the latest time to which you want to list records.

  6. Make a GET request to /contract-api/v1/reportingGroups/{reportingGroupId}/products/summaries{?from,to}.

Data

This section shows you the data model for the Contracts API. This API provides information about the products associated with either a specific contract (contractId) or a reporting group (reportingGroupId).

When using this API, keep in mind that you can only view information for contracts you have access to, and you can only run the reporting group operations if your user account includes the CPCode Rep Group role.

Download the JSON schemas for this API.

ContractHyperMedia

Lists the contracts that the requesting user has access to.

Download schema: contractHyperMediaList.json

Sample GET response:

{
    "contracts": [
        {
            "contractId": "3-ZQ0H6H",
            "href": "/contract-api/v1/contracts/3-ZQ0H6H/products/summaries"
        },
        {
            "contractId": "3-1EBV5F",
            "href": "/contract-api/v1/contracts/3-1EBV5F/products/summaries"
        },
        {
            "contractId": "3-XC1A0F",
            "href": "/contract-api/v1/contracts/3-XC1A0F/products/summaries"
        }
    ]
}

ContractHyperMedia members

Member Type Description
contracts ContractHyperMedia.contracts[] Array of contracts that the requesting user has access to.
ContractHyperMedia.contracts[]: Array of contracts that the requesting user has access to.
contractId String The unique identifier for a contract.
href String The URL that accesses product information for the contractId.

ProductSummary

Lists the products associated with specific contracts.

Download schema: productSummaries.json

Sample GET response:

{
    "products": {
        "contractId": "1-2RBL",
        "marketing-products": [
            {
                "marketingProductId": "B-3-96NY56",
                "marketingProductName": "Access Control - All Streaming Delivery"
            },
            {
                "marketingProductId": "B-3-A5ME5",
                "marketingProductName": "Site and Visitor Intelligence"
            },
            {
                "marketingProductId": "B-4-1O78TS",
                "marketingProductName": "All Streaming Delivery"
            }
        ]
    }
}

ProductSummary members

Member Type Description
products ProductSummary.products Object that lists the products associated with the contract specified.
ProductSummary.products: Object that lists the products associated with the contract specified.
contractId String The unique identifier for a contract.
marketing-products ProductSummary.products.marketing-products[] The identifiers and names for each product included on a contract.
ProductSummary.products.marketing-products[]: The identifiers and names for each product included on a contract.
marketingProductId String The unique identifier for a product.
marketingProductName String The formal name of a product.

ReportingGroup

A logical grouping of content provider (CP) codes.

Download schema: repGrpIdNameList.json

Sample GET response:

[
    {
        "id": 12289,
        "name": "foo.com group"
    },
    {
        "id": 139267,
        "name": "*.example.com"
    },
    {
        "id": 139268,
        "name": "images traffic group"
    },
    {
        "id": 7182,
        "name": "www.bar.com"
    },
    {
        "id": 13844,
        "name": "Radio and Streaming"
    },
    {
        "id": 130221,
        "name": "All Mini Country sites"
    }
]

ReportingGroup members

Member Type Description
id Integer Unique identifier for each reporting group.
name String The descriptive name you supply for each reporting group.

Errors

If you encounter a variety of errors, the Contracts API responds with appropriate HTTP status codes and a response object that explains them, detailed below.

There are many possible causes for failure, such as data input errors or a resource not being found.

This API responds with HTTP Problem error objects that provide details useful for debugging. For example:

{
    "status": "400",
    "title": "Erroneous data input.",
    "type": "/contract-api/error-types/E400",
    "errors": [
        {
            "detail": "From date must be within 15 months in past from the current date",
            "title": "from"
        },
        {
            "detail": "To date must be on or before the current date",
            "title": "to"
        }
    ]
}

HTTP status codes

The API responds with the following set of HTTP status codes for both success and failure scenarios.

Code Description
200 Request OK
300 Multiple Choice
400 Malformed Request
404 Resource not found

Last modified: 10/5/2017