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
acknowledgeAllWarningsflag 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
PENDINGactivations for the same network, typicallyPRODUCTION.
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:
-
Try another property. Check if prp_12346 is “free” and add your hostnames there instead. Keep going until you find a “free” property.
-
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
PENDINGactivation. 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.