/blueprint.apib
Created Mar 4, 2015
Un-uploadable blueprint
| FORMAT: 1A | |
| # Visitor Prioritization API V1 | |
| The Visitor Prioritization API enables you to manage your Visitor Prioritization policy. | |
| # Group Policy Commands | |
| <a name="policy-cmd"></a> | |
| [Click here](#properties) for the list of Policy properties. | |
| ## Policy JSON Document Considerations | |
| The Policy JSON document contains your rules. For this API, all JSON documents sent to the server use | |
| * `application/x-www-form-urlencoded` as the content type, and | |
| * this format: `query=<url-encoded JSON document>`, where the `query=` portion is *not* URL encoded. | |
| For example, the actual POST data for `getAllPolicyInfoMaps` will look something like this: | |
| > query=%7B%22policyManagerRequest%22%3A%7B%22command%22%3A%22getPolicyInfoMapUsingACGIDs%22%2C%22getPolicyInfoMapUsingACGIDs%22%3A%7B%7D%7D%7D | |
| ## Content-Length Header for Post Requests | |
| You **must** correctly set the `Content-Length` header for all POST requests to the server. | |
| ## POST Operations | |
| ## Get Information for All Policies [/config-visitor-prioritization-data/api/v1/policymanager?command=getAllPolicyInfoMaps] | |
| ### Get Information for All Policies [POST] | |
| Gets useful information about all policies. | |
| + Request (application/x-www-form-urlencoded) | |
| { | |
| "policyManagerRequest": { | |
| "command":"getPolicyInfoMapUsingACGIDs", | |
| "getPolicyInfoMapUsingACGIDs": {} | |
| } | |
| } | |
| + Response 200 (application/json) | |
| { | |
| "responseCode":0, | |
| "response":[ | |
| { | |
| "id":102, | |
| "policyId":101, | |
| "createdBy":"username", | |
| "createDate":1399880615407, | |
| "acgId":"3-10TQKCS", | |
| "version":1, | |
| "immutable":false, | |
| "activatedProduction":0, | |
| "activatedStaging":0, | |
| "activatedTest":0, | |
| "description":null, | |
| "policyName":"username_test", | |
| "assetId":0, | |
| "cloudletId":1, | |
| "cloudletConfig": { | |
| "id":1, | |
| "key":"VP", | |
| "name":"VISITORPRIORITIZATION", | |
| "featureKey":"visitor_prioritization", | |
| "engProduct":"Cloudlets::Visitor_Prioritization", | |
| "policyFileNamePrefix":"nimbus_", | |
| "openAPIContextRoot":"/configure-visitor-prioritization-data", | |
| "isInternal":false, | |
| "stagingLocation":null, | |
| "productionLocation":null, | |
| "logsLocation":null | |
| }, | |
| "policyDescription":"Test description.", | |
| "policyCreatedBy":"username", | |
| "policyLastModifiedBy":"username", | |
| "policyCreateDate":1399880598512, | |
| "policyLastModifiedDate":1399880615407, | |
| "matchRules":null | |
| } | |
| ], | |
| "i18nCode":0,"englishMessage":null | |
| } | |
| ## Create a Policy [/config-visitor-prioritization-data/api/v1/policymanager?command=create] | |
| ### Create [POST] | |
| Create a new Visitor Prioritization policy. | |
| + Request (application/x-www-form-urlencoded) | |
| { | |
| "policyManagerRequest":{ | |
| "command":"create", | |
| "create":{ | |
| "cloudletId":"1", | |
| "policyName":"TestPolicy3", | |
| "policyDescription":"TestPolicy3 notes." | |
| } | |
| } | |
| } | |
| + Response 200 (application/json) | |
| { | |
| "responseCode": 0, | |
| "response": [ | |
| { | |
| "id": 436, | |
| "policyId": 1001, | |
| "createdBy": "cloudlets", | |
| "createDate": 1400601368151, | |
| "acgId": "3-10TQKCS", | |
| "version": 2, | |
| "immutable": false, | |
| "activatedProduction": 0, | |
| "activatedStaging": 0, | |
| "activatedTest": 0, | |
| "description": "Description for all policy versions", | |
| "policyName": "Test1", | |
| "assetId": 0, | |
| "cloudletId": 1, | |
| "cloudletConfig": {}, | |
| "policyDescription": null, | |
| "policyCreatedBy": "cloudlets", | |
| "policyLastModifiedBy": "cloudlets", | |
| "policyCreateDate": 1400535431324, | |
| "policyLastModifiedDate": 1400601173283, | |
| "matchRules": null | |
| } | |
| ], | |
| "i18nCode": 0, | |
| "englishMessage": null | |
| } | |
| ## List a Policy [/config-visitor-prioritization-data/api/v1/policymanager?command=read] | |
| ### List [POST] | |
| List the configuration of a policy version. | |
| The rule configuration information is listed in the [`matchRules`](#matchrule-properties) field of the response JSON. | |
| + Request (application/x-www-form-urlencoded) | |
| {"policyManagerRequest":{"command":"read","read":{"id":"1133"}}} | |
| + Response 200 | |
| { | |
| "responseCode":0, | |
| "response":{ | |
| "id":1133, | |
| "policyId":686, | |
| "createdBy":"cloudlets", | |
| "createDate":1407339219183, | |
| "acgId":"3-10TQKCS", | |
| "version":1, | |
| "immutable":false, | |
| "activatedProduction":0, | |
| "activatedStaging":0, | |
| "activatedTest":0, | |
| "description":"Default description for all versions", | |
| "policyName":"1ERPolicy", | |
| "assetId":0, | |
| "cloudletId":1, | |
| "cloudletConfig":{ | |
| "id":0, | |
| "key":"VP", | |
| "name":"VISITORPRIORITIZATION", | |
| "featureKey":"visitor_prioritization", | |
| "engProduct":"Cloudlets::Visitor_Prioritization", | |
| "policyFileNamePrefix":"nimbus_", | |
| "openAPIContextRoot":"/config-visitor-prioritization-data", | |
| "isInternal":true, | |
| "stagingLocation":"tapioca_staging_ump_files", | |
| "productionLocation":"tapioca_ump_files", | |
| "logsLocation":null | |
| }, | |
| "policyDescription":"Sample Description", | |
| "policyCreatedBy":"cloudlets", | |
| "policyLastModifiedBy":"cloudlets", | |
| "policyCreateDate":1407160924865, | |
| "policyLastModifiedDate":1407339219183, | |
| "matchRules":[{ | |
| "type":"vpMatchRule", | |
| "end":0, | |
| "id":0, | |
| "matchURL":null, | |
| "matches":[{ | |
| "caseSensitive":false, | |
| "matchOperator":"contains", | |
| "matchType":"protocol", | |
| "matchValue":"http", | |
| "negate":false | |
| }, | |
| { | |
| "caseSensitive":false, | |
| "matchOperator":"contains", | |
| "matchType":"hostname", | |
| "matchValue":"source.com", | |
| "negate":false | |
| }, | |
| { | |
| "caseSensitive":false, | |
| "matchOperator":"contains", | |
| "matchType":"query", | |
| "matchValue":"test=null", | |
| "negate":false | |
| }], | |
| "name":"rule 1", | |
| "start":0, | |
| "useIncomingQueryString":false | |
| }] | |
| }, | |
| "i18nCode":0, | |
| "englishMessage":null | |
| } | |
| ## Update a Policy [/config-visitor-prioritization-data/api/v1/policymanager?command=update ] | |
| # Update [POST] | |
| Make updates to a Visitor Prioritization policy. | |
| **Note:** The response contains a new ID and other fields that were updated by the server. | |
| + Request (application/x-www-form-urlencoded) | |
| {"policyManagerRequest":{"command":"update","update":{"overwriteRules":true,"id":435,"policyId":122,"createdBy":"cloudlets","createDate":1400782263395,"version":10, | |
| "immutable":false,"activatedProduction":0,"activatedStaging":0,"activatedTest":0,"description":"Save a new version","policyName":"14_3VP_Policy", | |
| "assetId":0,"cloudletId":1,"cloudletConfig":{},"policyDescription":"specific version description","policyCreatedBy":"username", | |
| "policyLastModifiedBy":"cloudlets","policyCreateDate":1399997852450,"policyLastModifiedDate":1400782263395, | |
| "matchRules":[{"type":"vpMatchRule","end":0,"passThroughPercent":50,"id":0,"matchURL":"HTTP://akamai.com/sourceURL/update","name":"rule 1", | |
| "start":0,"useIncomingQueryString":true}]}}} | |
| + Response 200 (application/json) | |
| { | |
| "responseCode":0, | |
| "response":{ | |
| "id":436, | |
| "policyId":1001, | |
| "createdBy":"cloudlets", | |
| "createDate":1400782263395, | |
| "acgId":"3-10TQKCS", | |
| "version":10, | |
| "immutable":false, | |
| "activatedProduction":0, | |
| "activatedStaging":0, | |
| "activatedTest":0, | |
| "description":"Save a new version", | |
| "policyName":"14_3VP_Policy", | |
| "assetId":0, | |
| "cloudletId":1, | |
| "cloudletConfig":{}, | |
| "policyDescription":"specific version description", | |
| "policyCreatedBy":"username", | |
| "policyLastModifiedBy":"username2", | |
| "policyCreateDate":1399997852450, | |
| "policyLastModifiedDate":1400782263395, | |
| "matchRules":[ | |
| { | |
| "type":"vpMatchRule", | |
| "end":0, | |
| "id":0, | |
| "passThroughPercent":0.05, | |
| "matchURL":null, | |
| "matches":[ | |
| { | |
| "caseSensitive":false, | |
| "matchOperator":"contains", | |
| "matchType":"protocol", | |
| "matchValue":"HTTP", | |
| "negate":false | |
| }, | |
| { | |
| "caseSensitive":false, | |
| "matchOperator":"contains", | |
| "matchType":"hostname", | |
| "matchValue":"test.akamai.com", | |
| "negate":false | |
| }, | |
| { | |
| "caseSensitive":false, | |
| "matchOperator":"contains", | |
| "matchType":"path", | |
| "matchValue":"/sourceURL", | |
| "negate":false | |
| } | |
| ], | |
| "name":"rule 1", | |
| "start":0, | |
| "useIncomingQueryString":true | |
| } | |
| ] | |
| }, | |
| "i18nCode":0, | |
| "englishMessage":null | |
| } | |
| ## List Policy Information [/config-visitor-prioritization-data/api/v1/policymanager?command=getPolicyInfoList] | |
| ### List Policy Information [POST] | |
| List all information about each policy version, except for the `matchRules`. | |
| + Request (application/x-www-form-urlencoded) | |
| { | |
| "policyManagerRequest":{ | |
| "command":"getPolicyInfoList", | |
| "getPolicyInfoList":{ | |
| "policyId":"243" | |
| } | |
| } | |
| } | |
| + Response 200 (application/json) | |
| { | |
| "responseCode":0, | |
| "response":[{ | |
| "id":351, | |
| "policyId":243, | |
| "createdBy":"ccare2", | |
| "createDate":1403050992316, | |
| "acgId":"3-10TQKCS", | |
| "version":1, | |
| "immutable":false, | |
| "activatedProduction":0, | |
| "activatedStaging":0, | |
| "activatedTest":0, | |
| "description":null, | |
| "policyName":"Test_VP_Policy", | |
| "assetId":0, | |
| "cloudletId":1, | |
| "cloudletConfig":{ | |
| "id":0, | |
| "key":"VP", | |
| "name":"VISITORPRIORITIZATION", | |
| "featureKey":"visitor_prioritization", | |
| "engProduct":"Cloudlets::Visitor_Prioritization", | |
| "policyFileNamePrefix":"nimbus_", | |
| "openAPIContextRoot":"/config-visitor-prioritization-data", | |
| "isInternal":true, | |
| "stagingLocation":"tapioca_staging_ump_files", | |
| "productionLocation":"tapioca_ump_files", | |
| "logsLocation":null | |
| }, | |
| "policyDescription":null, | |
| "policyCreatedBy":"cloudletsuser", | |
| "policyLastModifiedBy":"testuser2", | |
| "policyCreateDate":1403036738153, | |
| "policyLastModifiedDate":1405438191162, | |
| "matchRules":null | |
| }], | |
| "i18nCode":0, | |
| "englishMessage":null | |
| } | |
| ## Clone a Policy [/config-visitor-prioritization-data/api/v1/policymanager?command=clone] | |
| ### Clone a Policy [POST] | |
| Make a copy of an existing policy version. | |
| **Note:** The new policy version will receive the next available version number. | |
| + Request (application/x-www-form-urlencoded) | |
| { | |
| "policyManagerRequest":{ | |
| "command":"clone", | |
| "clone":{ | |
| "id":"1149" | |
| } | |
| } | |
| } | |
| + Response 200 (application/json) | |
| { | |
| "responseCode":0, | |
| "response":{ | |
| "id":1178, | |
| "policyId":764, | |
| "createdBy":"cloudlets", | |
| "createDate":1407352490414, | |
| "acgId":"3-10TQKCS", | |
| "version":5, | |
| "immutable":false, | |
| "activatedProduction":0, | |
| "activatedStaging":0, | |
| "activatedTest":0, | |
| "description":null, | |
| "policyName":"TestPolicy3", | |
| "assetId":0, | |
| "cloudletId":1, | |
| "cloudletConfig":null, | |
| "policyDescription":"TestPolicy3 notes.", | |
| "policyCreatedBy":"cloudlets", | |
| "policyLastModifiedBy":"cloudlets", | |
| "policyCreateDate":1407348215182, | |
| "policyLastModifiedDate":1407348215182, | |
| "matchRules":null | |
| }, | |
| "i18nCode":0, | |
| "englishMessage":null | |
| } | |
| # Group Policy Activation Commands | |
| <a name="act-cmd"></a> | |
| [Click here](#properties) for the list of properties returned. | |
| ## Activate a Policy [/config-visitor-prioritization-data/api/v1/policymanager] | |
| ### Activate a Policy [POST] | |
| Activate a specified Cloudlet policy. | |
| **Note the following *before* using this command:** | |
| * You must first run the **List Policy Activation Info** command in order to get the correct `arlId` (`fileId`). | |
| * The `policyVersionId` corresponds to the `tapiocaIDs`. When issuing this command, make sure you are activating the correct version. | |
| The sample request uses `tapiocaIDs` (`policyVersionId`) 3668, which is version 1. | |
| * The generated policy file will be propagated to the selected environment. After activation completes, the policy will be available for use. | |
| + Request (application/x-www-form-urlencoded) | |
| { | |
| "policyManagerRequest":{ | |
| "command":"activate", | |
| "activate":{ | |
| "tapiocaIDs":[3668], | |
| "arlId":"217315", | |
| "assetId":"0", | |
| "network":"staging" | |
| } | |
| } | |
| } | |
| + Response 200 (application/json) | |
| + Body | |
| { | |
| "responseCode":0, | |
| "response":null, | |
| "i18nCode":0, | |
| "englishMessage":null | |
| } | |
| ## List Policy Activations [/config-visitor-prioritization-data/api/v1/common/activation{?historyOnly}] | |
| ### List Policy Activations [GET] | |
| List policies and provide policy-specific activation information. | |
| In the response, when | |
| * **historyOnly = true**, only the policy activation history is returned. | |
| * **historyOnly = false**, the history and the policies available for activation are returned. | |
| For example : | |
| + historyOnly (optional, string, `false`) ... If true, include the history. | |
| + Values | |
| + `true` | |
| + `false` | |
| **Please Note:** During activation you will need the `fileId`, which corresponds to the `arlId`. | |
| + Response 200 (application/json) | |
| + Body | |
| [ | |
| { | |
| "version":"2", | |
| "activatedPolicyVersions":[ | |
| { | |
| "stageStatus":"3000", | |
| "productionLastUpdated":null, | |
| "stageLastUpdated":1415297386000, | |
| "policies":[ | |
| { | |
| "policyName":"TestPolicyv1", | |
| "cloudletId":0, | |
| "versions":[ | |
| { | |
| "version":"1", | |
| "policyVersionId":3668, | |
| "acgId":"3-10TAKCB" | |
| } | |
| ], | |
| "id":2501 | |
| } | |
| ], | |
| "productionStatus":null, | |
| "fileId":217315, | |
| "createdBy":"tester", | |
| "assetId":0, | |
| "propertyName":"tester.akamai.com", | |
| "id":1421, | |
| "type":"ump" | |
| } | |
| ], | |
| ... | |
| # Group Properties | |
| <a name="properties"></a> | |
| This section provides information on the properties included in the requests or responses. | |
| The properties are grouped in the following categories: | |
| * policy properties | |
| * matchRules properties | |
| * matches properties | |
| * matchValue properties (examples only) | |
| ## Policy Properties | |
| <a name="policy-properties"></a> | |
| The Policy object has these properties. | |
| | Property | Description | | |
| |---|---| | |
| | **acgId** | Akamai use only. | |
| | **activatedProduction** | If `true`, this policy is activated in the production network. | |
| | **activatedStaging** | If `true`, this policy is activated in the staging network. | |
| | **activatedTest** | If `true`, this policy is activated in the test/QA network. | |
| | **arlId** | Also known as the `fileId`, this property is the ID associated with the Akamai Resource Locator (ARL). | |
| | **assetId** | Akamai use only. | |
| | **cloudletConfig** | Akamai use only. | |
| | **cloudletId** | Akamai use only. | |
| | **createdBy** | The name of the user who created this specific policy. | |
| | **createDate** | The date this specific policy was created (milliseconds since epoch). | |
| | **description** | The description of this specific policy. This property is not assigned by Akamai. | |
| | **fileId** | Also known as the `arlId`, this property is the ID associated with the Akamai Resource Locator (ARL). | |
| | **id** | The unique ID that corresponds to a specific policy. | |
| | **immutable** | Akamai use only. | |
| | **matchRules** | A JSON structure that defines the rules for this policy. This property is not assigned by Akamai. | |
| | **policyCreatedBy** | The user who created the initial policy. | |
| | **policyCreateDate** | The date the initial policy was created (milliseconds since epoch). | |
| | **policyDescription** | The default description for every version of the policy. This property is not assigned by Akamai. | |
| | **policyId** | Akamai use only. | |
| | **policyName** | The name used for every version of this policy. This property is not assigned by Akamai. | |
| | **policyLastModifiedBy** | The user who last modified the policy. | |
| | **policyLastModifiedDate** | The date the initial policy was modified (milliseconds since epoch). | |
| | **policyVersionId** | Also known as `tapiocaIDs`, this property is the ID associated with a specific policy version. | |
| | **tapiocaIDs** | Also known as `policyVersionId`, this property is the ID associated with a specific policy version. The expected value for this property is an array of integers. | |
| | **version** | The specific version of this policy. | |
| ## matchRules Properties | |
| The 'matchRules' property contains all of your rules. Some example use cases: | |
| * Pass through all HTTP requests that end in *jpg* or *png* with a probability of 95%. | |
| * Pass through HTTP requests with the vanity/marketing pathname of *'/shoes'* with a probability of 5%. | |
| <a name="matchrule-properties"></a> | |
| A `matchRules` property includes the following properties: | |
| | Property | Description | | |
| |---|---| | |
| | **end** | The end time (in milliseconds since the epoch) this match will be valid. | |
| | **id** | Akamai use only. | |
| | **matches** | See `matches` below. | |
| | **matchURL** | If using a URL match, this property is the URL that Visitor Prioritization will use to match the incoming request. | |
| | **name** | The name of the rule. | |
| | **passThroughPercent** | A value of -1 means send everyone to the waiting room. The range 0.000 - 99.000 specifies the percentage of requests that will pass through to the origin. The value of 100 means the request will always pass through to the origin. | |
| | **type** | The type of Cloudlet. For Visitor Prioritization use the string `vpMatchRule`. | |
| | **start** | The start time (in milliseconds since the epoch) this match will be valid. | |
| | **useIncomingQueryString** | If `true`, Visitor Prioritization will pass through the request query string. | |
| ### Matches Properties | |
| Each object in the `matches` property defines potential conditions (caseSensitive, matchType, matchValue, negate). | |
| If all of the conditions you set are true, then the Edge Server will pass the request through to the origin server based on your passThroughPercent setting. | |
| <a name="match-properties"></a> | |
| A `matches` property contains an array of objects with the following properties/conditions: | |
| | Property | Description | | |
| |---|---| | |
| | **caseSensitive** | If `true`, the match is case sensitive. | |
| | **matchOperator** | You must set this property to `contains`. | |
| | **matchType** | The type of match used. Possible values include: `hostname`, `path`, `extension`, `query`, `cookie`, `protocol`, `continent`, `countrycode`, and `regioncode`. | |
| | **matchValue** | This depends on the `matchType`. If the `matchType` is `hostname`, then `matchValue` will be the Fully qualified domain name, like `www.akamai.com`. See the `matchValue Examples` section below. | |
| | **negate** | If `true`, negates the match. | |
| #### matchValue Property Examples | |
| <a name="matchvalue-properties"></a> | |
| The `matchValue` properties provide information about the match types used to conditionally pass through the request. | |
| > **Note:** Match types with an **"m"** support multiple space-separated values (not names). | |
| | matchType | Description | matchValue Example | | |
| |---|---| --- | | |
| | **continent** | The continent to match on.| NA (See: https://control.akamai.com/dl/edgescape/continentCodes.csv) | |
| | **cookie** | The cookie value(s) to match on. | name=value1 | |
| | **countrycode** | The country to match on. | US (See: https://control.akamai.com/dl/edgescape/cc2continent.csv) | |
| | **extension (m)** | The file extension(s) to match on. | jpg png gif | |
| | **hostname (m)** | The hostname(s) to match on. | `www.akamai.com` | |
| | **path (m)** | The path(s) to match on. | /clothing/children/shoes/shoe1.jpg | |
| | **protocol** | The protocol to match on. | http | |
| | **query (m)** | The query value(s) to match on. | `name` or `name=value1` or `name=value1 value2` | |
| | **regioncode** | The region within a country to match on, like a state or province. | MA (See: https://control.akamai.com/dl/edgescape/region_codes.txt) | |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment