Plans

Resource URI

/packages/{packageId}/plans/{planId}

Items in curly braces represent variables.

Description

A plan object represents the set of key provisioning, limiting and entitlement rules that will be granted to developers. The plan specifies access to the array of services, endpoints and methods included in a plan as well as the limits associated with said access.

Resource Schema

Property Characteristics
id Type string
Sub-type
Create Rule Ignored
Update Rule Required (if not in context)
Fetch Rule Implicit
Description Object identifier.
created Type string
Sub-type datetime
Create Rule Ignored
Update Rule Ignored
Fetch Rule Implicit
Description Date/time the object was created.
updated Type string
Sub-type datetime
Create Rule Ignored
Update Rule Ignored
Fetch Rule Implicit
Description Date/time the object was updated.
name Type string
Sub-type
Create Rule Required
Update Rule Optional
Fetch Rule Implicit
Description Plan name.
description Type string
Sub-type
Create Rule Optional
Update Rule Optional
Fetch Rule Implicit
Description Plan description.
eav Type object
Sub-type
Create Rule Optional
Update Rule Optional
Fetch Rule Explicit
Description Extended attribute values.
selfServiceKeyProvisioningEnabled Type boolean
Sub-type
Create Rule Ignored
Update Rule Ignored
Fetch Rule Implicit
Description Is plan public.
adminKeyProvisioningEnabled Type boolean
Sub-type
Create Rule Optional
Update Rule Optional
Fetch Rule Implicit
Description Is plan moderated.
notes Type string
Sub-type
Create Rule Optional
Update Rule Optional
Fetch Rule Explicit
Description Notes for plan.
maxNumKeysAllowed Type integer
Sub-type
Create Rule Optional
Update Rule Optional
Fetch Rule Implicit
Description Maximum number of keys allowed per developer.
numKeysBeforeReview Type integer
Sub-type
Create Rule Optional
Update Rule Optional
Fetch Rule Implicit
Description Keys allowed before approval??
qpsLimitCeiling Type integer
Sub-type
Create Rule Optional
Update Rule Optional
Fetch Rule Implicit
Description Plan qps limit.
qpsLimitExempt Type boolean
Sub-type
Create Rule Optional
Update Rule Optional
Fetch Rule Implicit
Description Is plan exempt from qps limit.
qpsLimitKeyOverrideAllowed Type boolean
Sub-type
Create Rule Optional
Update Rule Optional
Fetch Rule Implicit
Description Can plan qps limit be overridden at key level.
rateLimitCeiling Type integer
Sub-type
Create Rule Optional
Update Rule Optional
Fetch Rule Implicit
Description Plan rate limit.
rateLimitExempt Type boolean
Sub-type
Create Rule Optional
Update Rule Optional
Fetch Rule Implicit
Description Is plan exempt from rate limit.
rateLimitKeyOverrideAllowed Type boolean
Sub-type
Create Rule Optional
Update Rule Optional
Fetch Rule Implicit
Description Can plan rate limit be overridden at key level.
rateLimitPeriod Type string
Sub-type enum
Create Rule Optional
Update Rule Optional
Fetch Rule Implicit
Description enum literals: minute, hour, day, month
responseFilterOverrideAllowed Type boolean
Sub-type
Create Rule Optional
Update Rule Optional
Fetch Rule Implicit
Description Can response filter be overridden??
status Type string
Sub-type enum
Create Rule Ignored
Update Rule Ignored
Fetch Rule Implicit
Description enum literals: active, inactive
emailTemplateSetId Type integer
Sub-type
Create Rule Optional
Update Rule Optional
Fetch Rule Explicit
Description Id for email template set to be used with plan.
services Type array
Sub-type PlanService
Create Rule Optional
Update Rule Optional
Fetch Rule Explicit
Description Services that belong to this plan.

fetch all [GET]

Retrieves collection of Plans belonging to the given Package.

Parameters

Parameter Required Type Description
packageId true string Package identifier.
fields false string Comma-separated list of property paths to include in response. Each property path is a dot-separated list of object property names. fields=<property\[.property...\]>\[,...\]\[&fields=...\]
filter false string

Colon-separated name/value pair specifying the name of property whose value must contain the given value (as a substring). Results may also be filtered by nested collections' properties by specifying a dot-separated property path. filter=<property\[.property...\]>:<value>\[&filter=...\]

For PAPI objects, the following rules apply for filtering: 

  • The property has to be filterable. Not all properties are filterable.
  • The filtering syntax is the following: filter-keyword=property-name:property-value.
  • The filtering is done based on property-value.
  • The keyword can be 'filter' or 'search'
  • Based on the keyword, the behavior is different.
  • If 'search' is specified, the filter value can be a substring. It gets translated into a LIKE query: (foo LIKE '%bar%'')
  • If 'filter' is specified, the filter value has to be an exact match. It gets translated into an '=' query (foo = 'bar')
  • Multiple search parameters can be specified and all 'search' parameters get AND'd into a single predicate
  • Multiple filter parameters can be specified and all 'filter' parameters get OR'd together. The resulting predicate is OR'd with the search predicate.
  • It is possible to filter boolean values: filter=foo:true
  • It is possible to filter for null (or not null) values: filter=foo:null
  • It is possible to provide a set of values separated by '|' E.g. filter=foo:red | yellow | green. This gets translated into an IN query (foo IN ('red, 'yellow', 'green'))
  • Filter and search parameters can be specified for nested objects: foo.bar.foobar
sort false string Comma-separated list of properties to sort by. Only root-level properties are supported. Each property name may be optionally followed by :asc or :desc to specify sort direction (defaults to asc). sort=<property\[:(asc\|desc)\]>\[,...\]\[&sort=...\]
limit false int Number of objects to return in the result. Defaults to 100.
offset false int 0-based index of first object in the list to return. Defaults to 0.

Returns

Success

Array of Plans for the Package If fields request parameter is not included, only those fields with "Fetch Rule" equal to "Implicit" will be returned. Otherwise, the fields contained in the URL parameter will be included in the response.

Failure

Array of validation responses

Examples

Request

curl -k 'https://api.mashery.com/v3/rest/packages/83cca97c-986b-468c-b277-525b633909a9/plans' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" 

Response

[
    {
        "qpsLimitExempt": true,
        "numKeysBeforeReview": 2,
        "qpsLimitCeiling": 36,
        "emailTemplateSetId": 25,
        "status": "active",
        "rateLimitKeyOverrideAllowed": false,
        "rateLimitExempt": true,
        "selfServiceKeyProvisioningEnabled": false,
        "adminKeyProvisioningEnabled": false,
        "id": "365b72d7-5542-49ac-a9ed-b93c9fe1365a",
        "maxNumKeysAllowed": 56,
        "created": "2013-07-18T07:17:50.000+0000",
        "updated": "2013-09-06T23:52:15.000+0000",
        "description": "id sapien in sapien iaculis congue vivamus metus arcu adipiscing",
        "name": "ultrices posuere",
        "responseFilterOverrideAllowed": true,
        "qpsLimitKeyOverrideAllowed": true,
        "notes": "nisi venenatis tristique",
        "rateLimitCeiling": 2,
        "rateLimitPeriod": "month"
    }
]

Request

curl -k 'https://api.mashery.com/v3/rest/packages/83cca97c-986b-468c-b277-525b633909a9/plans' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" 

Response

[
    {
        "qpsLimitExempt": true,
        "numKeysBeforeReview": 50,
        "qpsLimitCeiling": 96,
        "status": "active",
        "rateLimitKeyOverrideAllowed": true,
        "rateLimitExempt": true,
        "selfServiceKeyProvisioningEnabled": false,
        "adminKeyProvisioningEnabled": true,
        "id": "bdc9767d-0364-4666-bea5-7cc60c29ba8b",
        "maxNumKeysAllowed": 31,
        "created": "2013-08-29T07:46:06.000+0000",
        "updated": "2014-05-14T17:21:34.000+0000",
        "description": "mi nulla ac enim in tempor turpis nec euismod scelerisque quam turpis adipiscing lorem vitae mattis nibh",
        "name": "iaculis diam",
        "responseFilterOverrideAllowed": false,
        "qpsLimitKeyOverrideAllowed": true,
        "rateLimitCeiling": 45,
        "rateLimitPeriod": "hour"
    }
]

fetch [GET]

Retrieves the Plan, returning a Plan

Parameters

Parameter Required Type Description
packageId true string Package identifier.
planId true string Plan identifier.
fields false string Comma-separated list of property paths to include in response. Each property path is a dot-separated list of object property names. fields=<property\[.property...\]>\[,...\]\[&fields=...\]
filter false string

Colon-separated name/value pair specifying the name of property whose value must contain the given value (as a substring). Results may also be filtered by nested collections' properties by specifying a dot-separated property path. filter=<property\[.property...\]>:<value>\[&filter=...\]

For PAPI objects, the following rules apply for filtering: 

  • The property has to be filterable. Not all properties are filterable.
  • The filtering syntax is the following: filter-keyword=property-name:property-value.
  • The filtering is done based on property-value.
  • The keyword can be 'filter' or 'search'
  • Based on the keyword, the behavior is different.
  • If 'search' is specified, the filter value can be a substring. It gets translated into a LIKE query: (foo LIKE '%bar%'')
  • If 'filter' is specified, the filter value has to be an exact match. It gets translated into an '=' query (foo = 'bar')
  • Multiple search parameters can be specified and all 'search' parameters get AND'd into a single predicate
  • Multiple filter parameters can be specified and all 'filter' parameters get OR'd together. The resulting predicate is OR'd with the search predicate.
  • It is possible to filter boolean values: filter=foo:true
  • It is possible to filter for null (or not null) values: filter=foo:null
  • It is possible to provide a set of values separated by '|' E.g. filter=foo:red | yellow | green. This gets translated into an IN query (foo IN ('red, 'yellow', 'green'))
  • Filter and search parameters can be specified for nested objects: foo.bar.foobar
sort false string Comma-separated list of properties to sort by. Only root-level properties are supported. Each property name may be optionally followed by :asc or :desc to specify sort direction (defaults to asc). sort=<property\[:(asc\|desc)\]>\[,...\]\[&sort=...\]
limit false int Number of objects to return in the result. Defaults to 100.
offset false int 0-based index of first object in the list to return. Defaults to 0.
indent false boolean When set to true, responses are indented for better readability.

Returns

Success

Package as identified If fields request parameter is not included, only those fields with "Fetch Rule" equal to "Implicit" will be returned. Otherwise, the fields contained in the URL parameter will be included in the response.

Failure

Array of validation responses

Examples

Request

curl -k 'https://api.mashery.com/v3/rest/packages/83cca97c-986b-468c-b277-525b633909a9/plans/9c0e6072-b6a8-4085-877b-e3fb1c71bc73' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" 

Response

[
    {
        "qpsLimitExempt": true,
        "numKeysBeforeReview": 71,
        "qpsLimitCeiling": 56,
        "emailTemplateSetId": 13,
        "status": "inactive",
        "rateLimitKeyOverrideAllowed": false,
        "rateLimitExempt": true,
        "selfServiceKeyProvisioningEnabled": true,
        "adminKeyProvisioningEnabled": true,
        "id": "e461633e-771a-474f-85e6-c0272943147f",
        "maxNumKeysAllowed": 70,
        "created": "2014-02-05T00:47:32.000+0000",
        "updated": "2014-02-23T09:52:24.000+0000",
        "description": "sollicitudin ut suscipit a feugiat et eros vestibulum ac est lacinia nisi venenatis tristique fusce congue diam id ornare imperdiet",
        "name": "viverra eget congue",
        "responseFilterOverrideAllowed": true,
        "qpsLimitKeyOverrideAllowed": true,
        "notes": "sapien sapien non mi",
        "rateLimitCeiling": 34,
        "rateLimitPeriod": "minute"
    }
]

Request

curl -k 'https://api.mashery.com/v3/rest/packages/83cca97c-986b-468c-b277-525b633909a9/plans/9c0e6072-b6a8-4085-877b-e3fb1c71bc73' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" 

Response

[
    {
        "qpsLimitExempt": false,
        "numKeysBeforeReview": 82,
        "qpsLimitCeiling": 3,
        "status": "inactive",
        "rateLimitKeyOverrideAllowed": false,
        "rateLimitExempt": true,
        "selfServiceKeyProvisioningEnabled": true,
        "adminKeyProvisioningEnabled": false,
        "id": "93f53c72-3089-4cae-a8f0-60b81cca4cb5",
        "maxNumKeysAllowed": 25,
        "created": "2013-09-26T00:29:13.000+0000",
        "updated": "2013-09-25T14:22:54.000+0000",
        "description": "accumsan odio curabitur convallis duis consequat dui nec nisi volutpat eleifend donec ut dolor morbi vel",
        "name": "magnis dis parturient",
        "responseFilterOverrideAllowed": false,
        "qpsLimitKeyOverrideAllowed": false,
        "rateLimitCeiling": 31,
        "rateLimitPeriod": "minute"
    }
]

create [POST]

Creates a new Plan in the given Package.

Parameters

Parameter Required Type Description
packageId true string Package identifier.
plan true object Plan object

Returns

Success

Plan as created If fields request parameter is not included, only those fields with "Fetch Rule" equal to "Implicit" will be returned. Otherwise, the fields contained in the URL parameter will be included in the response.

Failure

Array of validation responses

Examples

Request

curl -k 'https://api.mashery.com/v3/rest/packages/83cca97c-986b-468c-b277-525b633909a9/plans' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" --request POST --data '{"qpsLimitExempt":false,"numKeysBeforeReview":2,"qpsLimitCeiling":63,"emailTemplateSetId":55,"status":"active","rateLimitKeyOverrideAllowed":false,"rateLimitExempt":false,"selfServiceKeyProvisioningEnabled":true,"adminKeyProvisioningEnabled":true,"id":"8b84bb39-65c6-4cbf-b19d-49b5a042d5f7","maxNumKeysAllowed":87,"created":"2014-07-05T05:48:34.000+0000","updated":"2014-05-01T20:04:27.000+0000","description":"ac enim in tempor turpis nec euismod scelerisque quam turpis","name":"quam pharetra magna","responseFilterOverrideAllowed":false,"qpsLimitKeyOverrideAllowed":true,"notes":"tincidunt lacus","rateLimitPeriod":"day","rateLimitCeiling":97}

Response

[
    {
        "qpsLimitExempt": true,
        "numKeysBeforeReview": 32,
        "qpsLimitCeiling": 17,
        "emailTemplateSetId": 21,
        "status": "active",
        "rateLimitKeyOverrideAllowed": false,
        "rateLimitExempt": false,
        "selfServiceKeyProvisioningEnabled": false,
        "adminKeyProvisioningEnabled": false,
        "id": "642db75a-a5de-4717-a6e2-2eb134915b23",
        "maxNumKeysAllowed": 27,
        "created": "2013-07-18T13:12:09.000+0000",
        "updated": "2013-10-06T12:16:42.000+0000",
        "description": "libero ut massa volutpat convallis morbi odio odio elementum eu interdum eu tincidunt in leo maecenas",
        "name": "quam",
        "responseFilterOverrideAllowed": false,
        "qpsLimitKeyOverrideAllowed": true,
        "notes": "luctus et ultrices",
        "rateLimitCeiling": 99,
        "rateLimitPeriod": "minute"
    }
]

Request

curl -k 'https://api.mashery.com/v3/rest/packages/83cca97c-986b-468c-b277-525b633909a9/plans' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" --request POST --data '{"qpsLimitExempt":true,"numKeysBeforeReview":85,"qpsLimitCeiling":55,"status":"active","rateLimitKeyOverrideAllowed":false,"rateLimitExempt":false,"selfServiceKeyProvisioningEnabled":true,"adminKeyProvisioningEnabled":false,"id":"37be5405-1c7b-42b6-b4f0-a905d1fa4c5b","maxNumKeysAllowed":74,"created":"2013-09-25T05:47:00.000+0000","updated":"2014-01-31T02:50:22.000+0000","description":"at nunc commodo placerat praesent blandit nam nulla integer pede justo lacinia eget tincidunt eget tempus vel","name":"orci eget","responseFilterOverrideAllowed":true,"qpsLimitKeyOverrideAllowed":false,"rateLimitPeriod":"minute","rateLimitCeiling":21}

Response

[
    {
        "qpsLimitExempt": true,
        "numKeysBeforeReview": 98,
        "qpsLimitCeiling": 34,
        "status": "inactive",
        "rateLimitKeyOverrideAllowed": true,
        "rateLimitExempt": false,
        "selfServiceKeyProvisioningEnabled": false,
        "adminKeyProvisioningEnabled": true,
        "id": "42d53829-daac-4285-815a-d49d891cb6a2",
        "maxNumKeysAllowed": 48,
        "created": "2014-04-07T04:36:18.000+0000",
        "updated": "2014-06-21T17:56:53.000+0000",
        "description": "pellentesque ultrices mattis odio donec vitae nisi nam ultrices libero non mattis pulvinar nulla pede ullamcorper augue a",
        "name": "turpis nec",
        "responseFilterOverrideAllowed": true,
        "qpsLimitKeyOverrideAllowed": true,
        "rateLimitCeiling": 27,
        "rateLimitPeriod": "hour"
    }
]

update [PUT]

Updates the identified Plan.

Parameters

Parameter Required Type Description
planId true string Plan identifier.
plan true object Plan object

Returns

Success

Plan as persisted If fields request parameter is not included, only those fields with "Fetch Rule" equal to "Implicit" will be returned. Otherwise, the fields contained in the URL parameter will be included in the response.

Failure

Array of validation responses

Examples

Request

curl -k 'https://api.mashery.com/v3/rest/packages/83cca97c-986b-468c-b277-525b633909a9/plans/9c0e6072-b6a8-4085-877b-e3fb1c71bc73' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" --request PUT --data '{"qpsLimitExempt":true,"numKeysBeforeReview":85,"qpsLimitCeiling":62,"emailTemplateSetId":21,"status":"inactive","rateLimitKeyOverrideAllowed":true,"rateLimitExempt":false,"selfServiceKeyProvisioningEnabled":true,"adminKeyProvisioningEnabled":false,"id":"e2e5556f-457d-46c2-9afa-342aadf98e53","maxNumKeysAllowed":39,"created":"2013-08-17T14:03:07.000+0000","updated":"2013-09-28T16:52:53.000+0000","description":"ipsum dolor sit amet consectetuer adipiscing elit proin risus praesent lectus vestibulum","name":"dictumst maecenas ut","responseFilterOverrideAllowed":false,"qpsLimitKeyOverrideAllowed":true,"notes":"sit amet lobortis","rateLimitPeriod":"day","rateLimitCeiling":47}

Response

[
    {
        "qpsLimitExempt": false,
        "numKeysBeforeReview": 60,
        "qpsLimitCeiling": 42,
        "emailTemplateSetId": 18,
        "status": "inactive",
        "rateLimitKeyOverrideAllowed": false,
        "rateLimitExempt": false,
        "selfServiceKeyProvisioningEnabled": true,
        "adminKeyProvisioningEnabled": true,
        "id": "31ca801b-5029-405d-8df7-d28c16c3b1ad",
        "maxNumKeysAllowed": 55,
        "created": "2014-04-08T09:26:14.000+0000",
        "updated": "2014-05-15T11:50:36.000+0000",
        "description": "nisi venenatis tristique fusce congue diam id ornare imperdiet sapien urna pretium nisl ut volutpat",
        "name": "sodales scelerisque mauris",
        "responseFilterOverrideAllowed": false,
        "qpsLimitKeyOverrideAllowed": false,
        "notes": "suspendisse potenti in eleifend",
        "rateLimitCeiling": 50,
        "rateLimitPeriod": "day"
    }
]

Request

curl -k 'https://api.mashery.com/v3/rest/packages/83cca97c-986b-468c-b277-525b633909a9/plans/9c0e6072-b6a8-4085-877b-e3fb1c71bc73' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" --request PUT --data '{"qpsLimitExempt":true,"numKeysBeforeReview":14,"qpsLimitCeiling":45,"status":"active","rateLimitKeyOverrideAllowed":true,"rateLimitExempt":true,"selfServiceKeyProvisioningEnabled":true,"adminKeyProvisioningEnabled":false,"id":"3d95de48-ccb0-4b02-9bc9-f718906111e4","maxNumKeysAllowed":76,"created":"2013-10-01T23:18:53.000+0000","updated":"2014-04-17T03:54:16.000+0000","description":"erat quisque erat eros viverra eget congue eget semper rutrum nulla nunc purus phasellus in","name":"leo maecenas pulvinar","responseFilterOverrideAllowed":true,"qpsLimitKeyOverrideAllowed":false,"rateLimitPeriod":"day","rateLimitCeiling":85}

Response

[
    {
        "qpsLimitExempt": false,
        "numKeysBeforeReview": 95,
        "qpsLimitCeiling": 1,
        "status": "inactive",
        "rateLimitKeyOverrideAllowed": true,
        "rateLimitExempt": false,
        "selfServiceKeyProvisioningEnabled": false,
        "adminKeyProvisioningEnabled": false,
        "id": "d518d2ba-d317-4f29-924c-85ec99d67622",
        "maxNumKeysAllowed": 85,
        "created": "2014-04-21T00:20:25.000+0000",
        "updated": "2014-06-26T22:07:30.000+0000",
        "description": "sed magna at nunc commodo placerat praesent blandit nam nulla integer pede justo lacinia eget tincidunt eget tempus",
        "name": "in",
        "responseFilterOverrideAllowed": true,
        "qpsLimitKeyOverrideAllowed": true,
        "rateLimitCeiling": 30,
        "rateLimitPeriod": "hour"
    }
]

delete [DELETE]

Deletes the identified Plan.

Parameters

Parameter Required Type Description
planId true string Plan identifier.

Returns

Success

Empty response

Failure

Array of validation responses

Examples

Request

curl -k 'https://api.mashery.com/v3/rest/packages/83cca97c-986b-468c-b277-525b633909a9/plans/9c0e6072-b6a8-4085-877b-e3fb1c71bc73' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" --request DELETE

Response

[
    ""
]

Request

curl -k 'https://api.mashery.com/v3/rest/packages/83cca97c-986b-468c-b277-525b633909a9/plans/9c0e6072-b6a8-4085-877b-e3fb1c71bc73' -H "Authorization: Bearer <insert your token here>" -H "Content-Type:application/json" --request DELETE

Response

[
    ""
]

Docs Navigation