Jay Sikkeland

Property Manager API (PAPI) Beta Changes and Roadmap

Blog Post created by Jay Sikkeland Employee on Jul 22, 2015

Dear Property Manager API (PAPI) beta user,

 

First of all, we hope all is going well with your PAPI beta testing!  PAPI represents a major part of Akamai’s strategic commitment to API enable the Akamai platform.

 

The reason for this blog post is that we are making some changes that you need to be aware of, especially note some changes required to code using the PAPI beta (v0) endpoint – See “2 - Naming Changes” below.

 

We also want to update you on the roadmap for PAPI for the rest of this year through the beginning of 2016.

 

Note the available PAPI resources:

 

If you have any feedback, we want to hear from you.  You can post feedback here in the Community site or contact your Akamai representative.

 

Regards,

 

The Akamai Property Manager Team.

 

 

 

1 – PAPI Roadmap

 

The following roadmap outlines the key milestones for PAPI over the next year.  Note that the exact dates are subject to change.

 

Portal Release 15.5 (currently scheduled for July 30 2015)

  • Behavior naming changes for PAPI v0.
    • See “2 - Naming Changes” below, as this may require changes to your code!
    • Because of feedback we received from the PAPI beta users we decided to make these naming changes now, while PAPI is still in beta.  Normally, all such naming and data model changes will be fully backwards compatible, but this time we had to make some changes that can break your code.  Future changes for PAPI will be backwards compatible for v0, even after v1 is released.
  • Rule Format.
    • The features (behaviors and matches) you can use with the Property Manager UI and PAPI depend on the Property Manager Catalog (“the Catalog”).  The Catalog has the detailed definitions of all the Akamai products you use.
    • The behaviors and criteria in the Catalog change continuously as Akamai adds or modifies features.
    • In the Property Manager UI, when there is a Catalog update, you will be prompted to accept the changes and to enter any additional required information.  This is not a big problem for users of the Property Manager UI, but for PAPI users, your API calls may suddenly return an error along with an error message indicating changes you need to make to the configuration.
    • We are therefore introducing the capability to lock down (or freeze) the Catalog features by specifying a Rule Format.  See the “Versioning API Features” in the PAPI documentation (https://developer.akamai.com/api/luna/papi/overview.html).
    • Roughly once per quarter, we will create a new Rule Format.  The first such Rule Format will be made available shortly after the 15.5 release on July 30.
    • We recommend that customers using PAPI to update or query configurations should use the Rule Format to avoid interruptions to their PAPI applications.
    • Note that the Property Manager User Interface does not yet support Rule Formats! If you use the Property Manager UI to update your configuration (or create a new version), it will automatically apply the latest Rule Format, and thus possibly break your PAPI applications!  Property Manager UI will support Rule Formats in the September release (see below).
    • Note that the Rule Format you specify is static, and any new features that Akamai releases will not be available to you until a new Rule Format is made available (roughly quarterly) and you update your code to use the new Rule Format.
  • Limit Overrides.
    • PAPI imposes certain usage limits.  We are adding the ability to override these limits for customers with special valid use cases.
    • See “3 – Per Account Limit Overrides” below.

 

Portal Release 15.6 (currently scheduled for September 3, 2015)

  • Option values and further naming changes.
    • As long as you are specifying the Rule Format, your existing code will not be affected.
    • We will provide a detailed list of the changes, so you can update your code before changing the Rule Format.
  • Rule Format UI.
    • The Property Manager UI will now support Rule Formats.  This will enable you to update configurations using both PAPI and the Property Manager UI, without potentially breaking your PAPI applications.
  • With this release, we will remove the “beta” label and PAPI v0 will effectively be treated as a production Open API.  In order to limit the number of PAPI versions, we decided to not introduce PAPI v1 at this time, but rather continue to support and enhance PAPI v0.

 

Portal Release 16.1 (currently scheduled for January, 2016)

  • PAPI v1.
    • Official PAPI release.
    • PAPI v1 will have a more flexible and scalable authentication/authorization model.
    • Users should switch to PAPI v1 as new features will only be supported on v1 going forward.
  • Deprecate PAPI v0.
    • PAPI v0 will continue to be supported for a 4 month deprecation period.

 

Q2, 2016 (April timeframe)

  • End Of Life PAPI v0.
    • You must switch to PAPI v1 prior to this time. 
    • End of Life notifications will be sent.

 

 

 

2 – Naming Changes

 

  • NOTE:  Impact for users of PAPI
    • PAPI applications may need to change!
    • GET:  Rule trees will have new names returned to the user in response body.
    • PUT and POST:  Rule trees will have new names returned to the user in response body.  This includes error messages that contain behavior names.
    • PUT and POST:  Rule trees will accept old and new names in the PUT/POST body forever.
    • Code that relies on rule tree input to PUT and POST will not have to change.
    • Code that inspects the output of GET, PUT and POST for specific behaviors will have to change.
    • We recommend that customers using PAPI to update or query configurations should specify the Rule Format (see above) to avoid interrupting their PAPI applications in the future.
  • The following changes are being made to the PAPI data model on July 30, specifically behaviors are being renamed to conform to a common standard.
    • aic => adaptiveImageCompression
    • akamaizertag => akamaizerTag
    • enableallmethodscacheh => allHttpInCacheHierarchy
    • conditionalOriginBehavior => allowCloudletsOrigins
    • allowdelete => allowDelete
    • allowpatch => allowPatch
    • allowpost => allowPost
    • allowput => allowPut
    • basedir => baseDirectory
    • breakconnect => breakConnection
    • negativettl => cacheError
    • cacheid => cacheId
    • cachekeyignorecase => cacheKeyIgnoreCase
    • cachekeyqueryparams => cacheKeyQueryParams
    • cachekeyrewrite => cacheKeyRewrite
    • postcaching => cachePost
    • cache302 => cacheRedirect
    • centralauth => centralAuthorization
    • chaseredirects => chaseRedirects
    • clientip => clientIp
    • clientipversion => clientIpVersion
    • construct_response => constructResponse
    • network_match => contentDeliveryNetwork
    • contenttype => contentType
    • cpcode => cpCode
    • receiptdelivery => deliveryReceipt
    • denyaccess => denyAccess
    • devicecharacteristics => deviceCharacteristic
    • edccacheid => deviceCharacteristicCacheId
    • edcheader => deviceCharacteristicHeader
    • dnsasyncrefresh => dnsAsyncRefresh
    • dnsprefresh => dnsPrefresh
    • protocoldowngrade => downgradeProtocol
    • downstreamcaching => downstreamCache
    • edgeconnect => edgeConnect
    • edge_image_converter => edgeImageConversion
    • elb_advanced => edgeLoadBalancingAdvanced
    • elb_data_center => edgeLoadBalancingDataCenter
    • elb_origin => edgeLoadBalancingOrigin
    • edgeoriginauth => edgeOriginAuthorization
    • edgescape => edgeScape
    • esi => edgeSideIncludes
    • enhancedakamaiprotocol => enhancedAkamaiProtocol
    • failaction => failAction
    • ext => fileExtension
    • feo => frontEndOptimization
    • gzipresponse => gzipResponse
    • hddata_advanced => hdDataAdvanced
    • healthdetect => healthDetection
    • hoit => hostname
    • imagemanagement => imageManager
    • mdc => instantConfig
    • largefileoptimizations => largeFileOptimization
    • bitratelimiting => limitBitRate
    • manifestrerouting => manifestRerouting
    • advancedmatch => matchAdvanced
    • matchcpcode => matchCpCode
    • responsecode => matchResponseCode
    • mediaclient => mediaClient
    • mfro => mediaFileRetrievalOptimization
    • modincomingreqheader => modifyIncomingRequestHeader
    • modincomingrespheader => modifyIncomingResponseHeader
    • modoutgoingreqheader => modifyOutgoingRequestHeader
    • modoutgoingrespheader => modifyOutgoingResponseHeader
    • netsession => netSession
    • networkconditionsheader => networkConditionsHeader
    • origintimeout => originTimeout
    • wildcard => path
    • clientpconns => persistentClientConnection
    • pconns => persistentConnection
    • pii => personallyIdentifiableInformation
    • predictiveprefetching => predictivePrefetching
    • prefetching => prefetch
    • prefetchableobject => prefetchable
    • cacheprefresh => prefreshCache
    • querystring => queryStringParameter
    • randomseek => randomSeek
    • readtimeout => readTimeout
    • rum => realUserMonitoring
    • refererchecking => refererChecking
    • removeqsbyname => removeQueryParameter
    • removevary => removeVary
    • reporting => report
    • requestcookie => requestCookie
    • requestheader => requestHeader
    • requestmethod => requestMethod
    • requestprotocol => requestProtocol
    • setresponsecode => responseCode
    • setresponsecookie => responseCookie
    • responseheader => responseHeader
    • objectcachingrestrictions => restrictObjectCaching
    • urlrewrite => rewriteUrl
    • rmaoptimizations => rmaOptimization
    • save_post_dca_processing => savePostDcaProcessing
    • scheduledinvalidation => scheduleInvalidation
    • segmentedcontentprotection => segmentedContentProtection
    • segmentedmediaoptimization => segmentedMediaOptimization
    • sim_error_codes => simulateErrorCode
    • siteshield => siteShield
    • subcustomerenable => subCustomer
    • sureroute => sureRoute
    • tcpoptimizations => tcpOptimization
    • tiereddistribution => tieredDistribution
    • connecttimeout => timeout
    • token_auth_match => tokenAuthorization
    • useragent => userAgent
    • userlocation => userLocation
    • usernetwork => userNetwork
    • validateetag => validateEntityTag
    • token_auth_verify => verifyTokenAuthorization
    • watermark_tokens => watermarkUrl
    • waf => webApplicationFirewall
    • asset_prioritization => apiPrioritization
    • audience_segmentation => audienceSegmentation
    • conditionalOriginId => cloudletsOrigin
    • edge_redirector => edgeRedirector
    • forward_rewrite => forwardRewrite
    • ip_geo_access => ipGeoAccess
    • saasdefinitions => saasDefinitions
    • savePostDcaProcessing => dynamicContentAssemblyOnPost
    • visitor_prioritization => visitorPrioritization
  • Going forward
    • We will be making further data model changes in the 15.6 release (currently scheduled for September 3), and a detailed list of these changes will be provided. 
    • As long as you specify the Rule Format, your PAPI application will not be affected.

 

3 – Per Account Limit Overrides

 

  • Some global limits are in place to protect the Akamai platform from accidental/rogue apps with infinite loops, etc.
  • The current limits are:
    • limits.hosts_per_property = 1000 (max # of hostnames per configuration - high water mark)
    • limits.elements_per_property = 1500 (# of behaviors and criteria in a single configuration)
    • limits.max_nested_rules = 5 (# of levels of nested rules)
    • limits.max_clientip_per_match = 300 (max ip ranges per client ip match - you can add additional client ip matches)
    • limits.clientip_per_property = 10 (max client ip matches per configuration)
    • limits.properties_per_contract = 1000 (max # of configurations per contract – high water mark)
    • limits.edgehostnames_per_contract = 1000 (max # of edge hostnames per contract – high water mark)
    • limits.activations = 20/day (# of configuration activations per day)
    • Cpcodes = 20/contract/day (# of new cpcodes you can create per day)
  • PAPI responses include HTTP headers with an “X-Limit-“ prefix, that help you keep track of the limits.  For instance, the X-Limit-Edgehostnames-Per-Contract-Limit header will return the current limits.edgehostnames_per_contract.
  • While we have not seen any customers hitting the limits yet, we recognize that some customers may have use cases that go beyond the global limits, and we have therefore added the ability to override them.
  • Should you require an increase of these limits for your use cases, please reach out to Akamai Customer Care or your Akamai account team and they can assist with getting the limits increased.

Outcomes