Created
March 4, 2015 21:41
-
-
Save jrep/b462c73a1838cf99790d to your computer and use it in GitHub Desktop.
Un-uploadable blueprint
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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