Manage Plan Entitlements

An entitlement is the relationship between an API and a plan, describing that a plan entitles a client application to invoke an API, and under what conditions.

Topics:

• Understand Plan Entitlements

• View Plan Entitlement Details

• Add an API Entitlement to a Plan

• Set Rate Limits for an Entitlement

• Publish and Unpublish an Entitlement in a Plan

• Activate and Deactivate an Entitlement in a Plan

• Remove an Entitlement from a Plan

Understand Plan Entitlements

An entitlement is the relationship between a plan and an API that defines how a client application can access the API.

There is a many-to-many relationship between plans and APIs. A given plan can have entitlements to multiple APIs; for example, to group related APIs. A given API can be entitled by multiple plans; for example, to provide different quality of service criteria. Note that two entitlements of the same plan cannot point to the same entire API, or to the same action in an API.

You must have a Plan Manager role to manage plan entitlements.

View Plan Entitlement Details

You can view the entitlements in a plan and details such as whether the entitlement is active or published.

To view the details of an entitlement:

1. On the Plans List page, click the plan whose entitlements you want to view.
2. Click the (Entitlements) tab.
3. To filter the list for active or inactive entitlements, click the Active or Inactive tab.
4. To filter the list for published or unpublished entitlements, click the Published or Unpublished tab.
5. To see all entitlements, click the All tab.
6. To view more details about an entitlement, click its name or the Expand icon to the right.

Add an API Entitlement to a Plan

A plan can have multiple entitlements.

To add an entitlement to a plan:

1. On the Plans List page, click the plan to which you want to add an entitlement.
2. Click the (Entitlements) tab.
3. Click Add Entitlement.
4. Select the API or APIs to you want to add to the plan.
5. Click Add.

Set Rate Limits for an Entitlement

You add rate limits on entitlements to control requests from a specific API to a plan. These rate limits only affect the API in the entitlement.

You can set multiple rate limit conditions. In this case, the most restrictive condition is the limiting factor. For example, you set two rate limit conditions, one for 1000 requests per second and another for 10000 requests per minute. The plan allows the full 10000 requests per minute, but if more than 1000 requests occur in any given second, the excess requests are rejected for that second.

If the API uses an Apiary specification, you can set rate limits for specific actions in the API. If the API does not use an Apiary specification, then you can only set rate limits at the API level.

To set a rate limit for a plan entitlement:

1. On the Plans list page, click the plan to which you want to apply a constraint.
2. Click the (Entitlements) tab.
3. Click the entitlement that you want to constrain.
4. To set a rate limit for the API, follow these steps:
   1. On the API tab, click Limited to set a specific rate limit.
   2. Click the text to enter the number of requests.
   3. Click the requests per list and select the time interval. Click Add Condition (+) to add another condition.
5. To set rate limits for actions in the API, follow these steps:
   1. Click the Action tab. If the API does not have a specification, you will not be able to add actions.
   2. Click Add Constraint.
   3. From the Add Actions dialog, select the action or actions to which to apply rate limits and click Add.
   4. Click the Rate Limit tab.
   5. Click Limited to set a specific rate limit.
   6. Click the text to enter the number of requests.
   7. Click the requests per list and select the time interval. Click Add Condition (+) to add another condition.
   8. Click the Constraint Span list and choose one of the following:

      • Action: The limits are associated with each action. For example, a rate limit of 100 per second means that every action can be invoked 100 times per second.

      • Group: The limits are associated with all of the actions in the group. For example, a rate limit of 100 per second means that all actions in the group combined can be invoked 100 times second.

6. Click the Constraints Level list at the top of the Constraints box and select one of the following:
   • API: All invocations of the API will use the limits defined at the API level, even if there are also ones defined at the actions level.
   • Action: All invocations of the API will use the limits defined at the action level. If no actions are configured, the invocation will be rejected.
7. Click Save.
   

Publish and Unpublish an Entitlement in a Plan

Publishing an entitlement makes it available to application developers in the Developer Portal.

To publish or unpublish an entitlement in a plan:

1. On the Plans List page, click the plan for which you want to publish or unpublish an entitlement.
2. Click the (Entitlements) tab.
3. Click the entitlement that you want to publish or unpublish.
4. Click the Publish or Unpublish button.
5. Click Yes.

Activate and Deactivate an Entitlement in a Plan

A plan must be active for it to be available for use.

To activate or deactivate an entitlement in a plan:

1. On the Plans List page, click the plan for which you want to publish or unpublish an entitlement.
2. Click the (Entitlements) tab.
3. Click the entitlement that you want to publish or unpublish.
4. Click the Activate or Deactivate button.
5. Click Yes.

Remove an Entitlement from a Plan

Removing an entitlement removes access to all the APIs in the entitlement.

To remove an entitlement in a plan:

1. On the Plans List page, click the plan for which you want to remove an entitlement.
2. Click the (Entitlements) tab.
3. Click the entitlement that you want to remove.
4. Click the Remove button.
5. Click Yes.