Best practices interacting with PAPI

Follow these best practices when interacting with the Property Manager API.

Avoid race conditions

If you have multiple instances or machines trying to update or activate Akamai properties in parallel, you may run into race conditions. Ideally, you set up a single process that makes PAPI calls to avoid this. Alternatively, you can use the error handling and back-off algorithm recommendations to reduce most race conditions.

Exponential back-off algorithm

To avoid excessive load on the system, implement an exponential back-off algorithm for all error conditions that require a retry. Start with a retry after a few seconds, then increment the delay by 10 seconds for subsequent retries.

Property activations

By default, PAPI requires an acknowledgment of any warnings before activating a property. This is resource intensive and can lead to submitting multiple requests.

The response output almost always includes some warnings, so you end up making an activation request, getting a 400 response, parsing the response body looking for all the warnings, then resubmitting the activation request listing all the warnings youโ€™re acknowledging, and finally getting a 201 response that the activation was successfully submitted.

๐Ÿ‘

Use the acknowledgeAllWarnings flag for all activations.

To avoid an entire request and response, and to simplify the activation logic, set the acknowledgeAllWarnings flag to true when you Create a new activation or deactivation. This avoids unnecessary retries in case you donโ€™t acknowledge all warnings completely in the second request. The request flow to activate a property is:

POST /papi/v1/properties/prp_12345/activations
{
    "propertyVersion": 1,
    "network": "PRODUCTION",
    "note": "A better activation",
    "useFastFallback": false,
    "notifyEmails": [
        "you@example.com"
    ],
    "acknowledgeAllWarnings": true
}

Unless there are actual errors and not warnings, you'll get a 201 response with an activation status link in the response body:

{
    "activationLink": "/papi/v1/properties/prp_12345/activations/atv_6789?contractId=ctr_1111&groupId=grp_2222"
}

Check pending activations before activating

You can't have multiple simultaneous activations (this includes hostname changes) on a single property.

For example, if youโ€™re trying to add a hostname to propertyA, the activation will fail with a 409 response if another version of propertyA is in the process of being activated with status=PENDING.

๐Ÿ‘

Check for pending activations before creating a new version and activating it.

To check for pending activations, perform a List activations operation:

{
    "accountId": "act_1111",
    "contractId": "ctr_2222",
    "groupId": "grp_3333",
    "activations": {
        "items": [
            {
                "activationId": "atv_9876",
                "propertyName": "example.com",
                "propertyId": "prp_12345",
                "propertyVersion": 1,
                "network": "PRODUCTION",
                "activationType": "ACTIVATE",
                "status": "PENDING",
                "submitDate": "2021-03-02T02:22:12Z",
                "updateDate": "2021-03-01T21:12:57Z",
                "note": "Sample activation",
                "fmaActivationState": "steady",
                "notifyEmails": [
                    "you@example.com"
                ],
                "fallbackInfo": {
                    "fastFallbackAttempted": false,
                    "fallbackVersion": 10,
                    "canFastFallback": true,
                    "steadyStateTime": 1506448172,
                    "fastFallbackExpirationTime": 1506451772,
                    "fastFallbackRecoveryState": null
                }
            }
        ]
    }
}

๐Ÿ“˜

Look for PENDING activations for the same network, typically PRODUCTION.

Updates to production

If you're updating production, you can ignore all ACTIVE and PENDING activations that appear on the STAGING network.

If there are no PENDING activations on PRODUCTION, you can go ahead and create a new version, add the hostnames, and activate it. Otherwise, you have two choices:

  1. Try another property. Check if prp_12346 is โ€œfreeโ€ and add your hostnames there instead. Keep going until you find a โ€œfreeโ€ property.

  2. Wait for the previous activation to complete. Use a reasonable back-off algorithm. For instance, wait one minute, then two, and keep checking the status of the PENDING activation. You can just poll the 1 PENDING activation instead of listing all activations, e.g. GET /papi/v1/properties/prp_12345/activations/atv_9876

Activation error handling

The property activation process starts with a POST request to the PAPI activations endpoint (/papi/v1/properties/prp_12345/activations) along with a request body that includes acknowledgeAllWarnings=true.

{
    "propertyVersion": 1,
    "network": "PRODUCTION",
    "note": "A better activation",
    "useFastFallback": false,
    "notifyEmails": [
        "you@example.com"
    ],
    "acknowledgeAllWarnings": true
}

Unless there are actual errors, and not warnings, you should get a 201 response with an activation status link in the response body:

Response: 201
Response Headers:
X-RateLimit-Activations-Limit: 2500
X-RateLimit-Activations-Remaining: 9
X-RateLimit-Activations-Reset: 1636572611000
Response Body:
{
    "activationLink": "/papi/v1/properties/prp_12345/activations/atv_6789?contractId=ctr_1111&groupId=grp_2222"
}

๐Ÿ“˜

The X-RateLimit-Activations-* headers will tell you how close you are to exceeding the daily activation limits and when the 24 hour window resets.

Perform a Get an activation operation to check the status of the activation.

Response: 200
Response Headers: 	Retry-After: 600  << note this number is static
{
    "accountId": "act_0000",
    "contractId": "ctr_1111",
    "groupId": "grp_2222",
    "activations": {
        "items": [
            {
                "activationId": "atv_6789",
                "propertyName": "example property",
                "propertyId": "prp_12345",
                "propertyVersion": 1,
                "network": "PRODUCTION",
                "activationType": "ACTIVATE",
                "status": "PENDING",
                "submitDate": "2021-03-02T02:22:12Z",
                "updateDate": "2021-03-01T21:12:57Z",
                "note": "A better activation",
                "fmaActivationState": "received",
                "notifyEmails": [
                    "you@example.com"
                ]
            }
        ]
    }
}

For activations whose status is PENDING, the Retry-After header provides an estimate for when itโ€™s likely to change and thus when you should check status again.

๐Ÿ“˜

This is currently a static value, typically activations take ~10 min in PRODUCTION, but they can take much longer in certain circumstances, like when youโ€™re adding more than 10 hostnames which can take over an hour.

Once the activation is completed, perform a Get an activation operation to check the status:

Response: 200
Response Body:
{
    "accountId": "act_0000",
    "contractId": "ctr_1111",
    "groupId": "grp_2222",
    "activations": {
        "items": [
            {
                "activationId": "atv_6789",
                "propertyName": "example property",
                "propertyId": "prp_12345",
                "propertyVersion": 1,
                "network": "PRODUCTION",
                "activationType": "ACTIVATE",
                "status": "ACTIVE",
                "submitDate": "2021-03-02T02:22:12Z",
                "updateDate": "2021-03-01T21:12:57Z",
                "note": "A better activation",
                "fmaActivationState": "steady",
                "notifyEmails": [
                    "you@example.com"
                ]
            }
        ]
    }
}

You can now perform another activation of the property on that network (PRODUCTION or STAGING).

To reduce activation errors, use the acknowledgeAllWarnings=true flag and wait for the activation status=ACTIVE before submitting additional activation requests.

Occasionally things go wrong. See specific activation errors for more recommendations.