ParameterTypeSampleDescriptionURL path parameterspropertyIdStringprp_175780Unique identifier for the property. The parameter is optional if the property has been provisioned under only one contract. Otherwise you need to specify it along with the groupId.
The parameter is optional if the property has been provisioned under only one group. Otherwise you need to specify it along with the contractId. This is faster than the default full validation, which performs more extensive checks on the converted XML metadata configuration.validateRulesBooleantrueSet to true by default. When false, skips validation tests that would identify potential problems within the response object's errors and warnings arrays.
See the JSON problems section for details on this error feedback. See Fast validation, activation, and fallback for details on the delays this might avoid. This operation searches properties either by name, hostname or edge hostname for which it's currently active. Specify a Search request object with a single query member. The response lists the matching set of currently active property versions, and also the latest version if inactive. Each of the response'sVersion objects features additional context for the property in which it appears, or the account, contract, or group under which they're deployed.
Note that to perform more complex searches for content within a rule tree, runBulk search a set of properties instead. See Property hostname errors for details on relevant error feedback. POST aBulkSearch object to search across all active property versions, specifying aJSONPath expression to match their rule trees. This operation launches an asynchronous process to gather search results. To check its progress, run theList bulk search results operation, whose link is available in the Location header or the bulkSearchLinkmember of this operation's response.
After gathering completed results, you can create new property versions, bulk patch the rule trees, then activate them. SeeBulk Search and Updatefor guidance on this feature. Run Synchronously bulk search a set of properties as an alternative to get completed search results directly. To perform simpler searches for a property's name or hostnames to which it applies, run the Search properties operation instead.
Apply a series of JSON Patch operations to modify a set of property versions. Form this set of patches based on theJSONPath locations from a bulk search response. Specify a set of new property versions based on the results of abulk versioning operation. This operation launches an asynchronous process to update rule trees. To check its progress, run the List bulk-updated properties operation, whose link is available in the Location header or bulkPatchLink member of this operation's response. SeeBulk Search and Updatefor overall guidance on this feature.
Provides an alternative to the asynchronous Bulk search a set of properties operation. It yields completed bulk search results directly, but with possibly high latency, making it more appropriate to target for small-batch searches. POST a BulkSearch object to search across all active property versions, specifying aJSONPath expression to match their rule trees. After gathering results, you can create new property versions, bulk patch the rule trees, then activate them. See Bulk Search and Update for guidance on this feature.
Bulk searches use a flexible JSON path-based query syntax to search across all your activated property versions' rule trees. After your search request, search results become available asynchronously for all matching property versions. They include JSON path expressions that locate all the rule tree behaviors and criteria you searched on, for use in a subsequent bulk patch operation. This section shows you how to search across all your properties, then create a new set of editable property versions based on the results.
It shows you how to patch a set of configurations to modify them, then activate the entire set of modified properties on Akamai's staging and production networks. To write a rule tree to a property version, make a PUT request to the same resource as the GET request that reads it, passing in the rule object in the body of the request. See theRule Treessection for details on the rule tree's structure. Use this operation also tofreeze a set of rulesto a rule format version to ensure no change in a deployed activation's behavior. Set the validateRules query parameter to false to bypass a set of validation tests that may significantly slow this operation's execution time. SeeFast validation and activationfor guidance on when to defer validation.
SeeJSON problemsfor information on how validation data is embedded within the response object. Modify the set of hostnames for a property version. For new entries, specify an add array with a cnameFrom set to the hostname that your end users see, that is the Host header in end user requests. In eithercnameTo or edgeHostnameId, specify an existing edge hostname that you want to redirect your hostname to.
If you're using Secure by Default, you can set the cnameTo parameter to an edge hostname that doesn't exist yet, and PAPI creates it automatically when you activate the property version. To remove a hostname, specify a remove array with the address of the hostname you don't want to use with this property version anymore. If you remove an edge hostname from an active property configuration, use theEdge Hostname API to delete it entirely. To validate a rule tree to the requirements of a specific rule format, seeGet a rule format's schema.
List all property versions that result from a bulk search request. Run this operation to poll the asynchronous process's status. Once thesearchTargetStatus is COMPLETE, you can feed theresults into abulk versioning operation. Also use the JSON path matchLocations to run abulk patch operation over the rule trees.
Modify the set of hostname entries for a property version. For each hostname entry, set cnameFrom to the hostname that your end users see, that is the Host header in end user requests. You use rule formats to freeze or update the versioned set of behaviors and criteria a rule tree invokes. PAPI users should assign the most recent dated rule format to freeze the set of features. Otherwise, if you assign the latest rule format, features update automatically to their most recent version.
This may abruptly result in errors if JSON objects your rules specify no longer comply with the most recent feature's set of requirements. PAPI provides a more stable path to update rule formats that fixes these requirements for you. Relevant response objects appear within the outer Envelope object's customOverrides.items array. See Custom behaviors and overrides for guidance on custom overrides. This operation creates a new property activation, which deactivates any current activation. Updating to a more recent rule format modifies the rule tree to accommodate renamed options, renamed enumeration values, and two-state enums retyped as boolean.
Other values may not be able to convert, such as string numerics retyped as actual numerics, or if an updated behavior features a new required option or different validation criteria. If this occurs, the PUT response's rule tree object includes errors that help you refine the updated rule tree, as detailed in theErrors section. See ID prefixes for details on omitting the value's prp_ prefix.Optional query parameterscontractIdStringctr_1-1TJZFWUnique identifier for the contract. The only nominally mandatory member when saving a rule is its name, so you don't have to pass in the options object, as in this example that displays default behavior. TheCreate a new edge hostnameoperation shows how to specify hostnames as secure.
When the property's is_secure is set to true, it means you want to apply a shared certificate for all hostnames, possibly supplementing hostname-specific certificates. With is_secure enabled within the rule tree, you may receive warnings about any non-secure hostnames to which the rule applies. Note that some behaviors may only be available within the rule when is_secure is true. Bulk activate a set of property versions.
This operation launches an asynchronous process to update properties. To check its progress, run theList bulk-activated propertiesoperation, whose link is available in the Location header orbulkActivationLink member of this operation's response. (In other operations that don't specify a propertyId URL parameter, this parameter is always required.) See ID prefixes for details on omitting the value's grp_ prefix.
Specifies an edge hostname that's applied to a property version. Writing data to this resource requires that you PUT an array of all the hostname objects, each containing edgeHostnameId, cnameFrom, and cnameTo members. This request array matches the hostnames.items in the response. Specifies a set of available hostnames to which a property version may be applied. To POST a new edge hostname, specify a single object with productId, domainPrefix, and domainSuffix members, and optional ipVersionBehavior and secure members.
Relevant response objects appear within the outer Envelope object's edgehostnames.items array. Gets the entire rule tree for a property version. See theRule Treessection for details on the response object's structure. Also use this operation to update from one rule format to another more recent version, incrementing the assigned set of features.
SeeUpdate rules to a newer set of features. ParameterTypeSampleDescriptionURL path parametersedgeHostnameIdStringehn_887436Unique identifier for the edge hostname. See ID prefixes for details on omitting the value's ehn_ prefix.Required query parameterscontractIdStringctr_1-1TJZFWUnique identifier for the contract. See ID prefixes for details on omitting the value's ctr_ prefix.groupIdStringgrp_15166Unique identifier for the group.
SeeUpdate client settingsto set the default rule format for new properties. PAPI tracks rule formats in a database keyed by rule format version date strings. List all new property versions that result from abulk versioning request, and poll the asynchronous process's status. The response is a BulkVersion GET object. After the bulkCreateVersionsStatus is COMPLETE, use the new version numbers along with search paths from abulk searchoperation tobulk patchthem.
This operation lists the set of products that are available under a given contract. You need a product identifier to create new edge hostnames, CP codes, or properties. The range of rule behaviors available within a property is determined by the assigned product. However, as in all programming environments, no validation mechanism can identify all potential bugs, so you need to carefully step through the code. Contact your Akamai Professional Services representative if you need help understanding the metadata syntax.
This section shows you how to handle various kinds of error responses the Property Manager API generates. The bulkPatchStatus reflects the status of the overall bulk patch process. If its value isn't yetCOMPLETE when you poll the operation, wait some time and call the operation again later. Once you declare a variable within the default rule's variablesarray, you assign a value to it using thesetVariablebehavior, which you can place anywhere as appropriate within the rule tree. This example assigns the value of the built-in AK_EXTENSIONvariable to store the request's file extension in a user variable named EXT.
In this example, setting the TRANSFORM to NONEmeans you don't yet want to change the value. The default rule needs to include a set of behaviors, represented as an array of objects. New properties come with different sets of default rules depending on the product, but this much simpler example features the two behaviors that are always necessary to activate your property.
Theoriginbehavior determines how the edge network interacts with your origin servers, and you need thecpCodebehavior for billing and reporting on traffic. A property's main functionality is encapsulated in its set of rules. This section details how rules operate, how to configure prerequisite features, and how to structure the rest of a rule tree from the root down.
It also shows how to deal with special read-only features, and to interpret contextual rule format JSON schemas that specify your product's level of support for various behaviors and criteria. Activates property versions on a specific network. Relevant response objects appear within the outer Envelope object's activations.items array.
POST a BulkVersion object to create new versions of a set of properties based on any previous version. This operation launches an asynchronous process to increment versions. To check its progress, run the List bulk-versioned propertiesoperation, whose link is available in the Location header orbulkCreateVersionLink member of this operation's response. Run this operation only afterbulk searching a set of properties you want to change, to prepare new versions to bulk patch. Use this procedure to update the set of features assigned to your rule format.
This also modifies the rule tree to implement most required syntax changes, such as changes to option names and enum values. You can't use this approach to assign an older rule format. In this procedure, the initial GET operation specifies a MIME type that converts the rule tree, after which you PUT the converted object to write it back.
Both the rule tree and the set of hostnames are part of the same property definition, for which there's a single validation process. The benefits of routinely deferring validation increases along with the size of the rule tree, and with the number of hostnames you assign it to. When you defer validation, the response object comes to you more quickly, and without its usual errors and warnings arrays described in the JSON problems section. Note that you'd still need to fix any errors, and to either fix or acknowledge any warnings. To get this information, you need to enable validation again before activating the property.
You use PAPI to assign either a newly created or an already existing edge hostname to a hostname on a property. Many behavior and criteria options allow you to inject variable text that interprets at runtime on edge servers, typically based on details about the client request. PAPI allows you to reference a set of built-in system variables, and create your own set of variables based on various inputs. The section onVariablesclarifies how to insert variables within a rule tree, and how to declare and modify your own variables. A list is a set of index-accessible objects that provides functionality for searching, sorting, and manipulating list items. C# List class represents a collection of strongly typed objects that can be accessed by using the index.
