Creating a Usage Plan

To create a new usage plan and one or more entitlements using the Console:

1. In the Console, open the navigation menu and click Developer Services. Under API Management, click Gateways.
2. Choose a Compartment you have permission to work in.

3. On the Usage Plans page, click Create Usage Plan and specify:

   • Name: The name of the new usage plan. For example, Gold-usage-plan. Avoid entering confidential information.
   • Compartment: The compartment to which the new usage plan is to belong.
4. Optionally, click Advanced Options and specify:
   • Tags: If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you're not sure whether to apply tags, skip this option or ask an administrator. You can apply tags later.

5. Click Next to specify the API deployments that API consumers and API clients subscribed to the usage plan are entitled to access.

   A usage plan comprises entitlements. Each entitlement specifies one or more target API deployments to which subscribers to the usage plan are entitled to send requests, along with the number of requests they are entitled to send.

6. On the Entitlements page:

   1. Click Create Entitlement and specify details for the usage plan's first entitlement:

      • Name: The name of the new entitlement. Entitlement names must be unique within a usage plan. For example, Entitlement1. Avoid entering confidential information.
      • Description: A description of the new entitlement. For example, Basic entitlement for all usage plans. Avoid entering confidential information.
      • Rate Limit: (Optional) Select Enable Rate Limit to specify a maximum number of requests to allow per second as Requests per second.
      • Quota: (Optional) Select Enable Quota to specify a maximum number of requests to allow in a given time period:
        • Requests: Maximum number of requests to allow.
        • Period: Time period to which the maximum number of requests applies. One of Minute, Hour, Day, Week, or Month.

        • Reset Policy: When to reset the count of the number of requests to zero. The Calendar reset policy is supported. With the Calendar reset policy, the request number count is reset to zero at the start of each new time period, as specified by Period.

          For example, if Period is set to Day, the request number count is initially set to zero when the entitlement is first created. The count is then reset to zero at the start of the following day (that is, at midnight UTC). The count is reset to zero at the start of the next day, and so on.

        • Operation on breach: What happens if the maximum number of requests in the time period you specify is exceeded. If you specify Reject, additional requests in the time period are rejected and return an HTTP-429 Too Many Requests response. The response includes the Retry-After header, indicating how long to wait before making a new request. If you specify Allow, additional requests in the time period are still allowed.
      • Targeted Deployment: Click Add Deployment to specify the first API deployment to include in the entitlement:
        • Gateway: Select the API gateway on which the API deployment has been created. The API gateway can belong to the same compartment as the usage plan, but does not have to.
        • Deployment: Select the API deployment that you want to include in the entitlement. The API deployment can belong to the same compartment as the usage plan, but does not have to.

          Note that you must have already made the API deployment eligible for inclusion in the usage plan by specifying the location of a client token (see Making an API Deployment Eligible for Inclusion in a Usage Plan).

        Click Save to save details of the first API deployment included in the entitlement. Optionally, click Add Deployment again to specify additional API deployments to include in the usage plan's first entitlement.

   2. Click Save to save the usage plan's first entitlement.
   3. Optionally, click Create Entitlement again and specify details for additional entitlements to include in the usage plan.
7. Click Next to review the details you entered for the usage plan.
8. Click Create to create the usage plan.

   Note that it can take a few minutes to create the new usage plan. While it is being created, the usage plan is shown with a state of Creating on the Usage Plans page. When it has been created successfully, the new usage plan is shown with a state of Active.

   Also note that rather than creating the new usage plan immediately, you can create it later using Resource Manager and Terraform, by clicking Save as stack to save the resource definition as a Terraform configuration. For more information about saving stacks from resource definitions, see Creating a Stack from a Resource Creation Page.

9. If you have waited more than a few minutes for the usage plan to be shown with an Active state (or if the usage plan creation operation has failed):

   1. Click the name of the usage plan, and click Work Requests to see an overview of the usage plan creation operation.
   2. Click the Create Usage Plan operation to see more information about the operation (including error messages, log messages, and the status of associated resources).
   3. If the usage plan creation operation has failed and you cannot diagnose the cause of the problem from the work request information, see Troubleshooting API Gateway.

To create a new usage plan and one or more entitlements using the CLI:

1. Using your preferred JSON editor, create a usage plan definition file in the format:

   {
       "displayName": "<usage-plan-name>",
       "entitlements": [{
           "name": "<entitlement-name>",
           "description": "<entitlement-description>",
           "rateLimit": {
               "value": <rate-limit-value>,
               "unit": "<rate-limit-unit>"
           },
           "quota": {
               "value": <quota-value>,
               "unit": "<quota-unit>",
               "resetPolicy": "CALENDAR",
               "operationOnBreach": "<REJECT|ALLOW>"
           },
           "targets": [{
               "deploymentId": "<target-deployment-ocid>"
           }]
       }],
       "compartmentId": "<compartment-ocid>",
       "freeformTags": {},
       "definedTags": {}
   }

   where:

   • "displayName": "<usage-plan-name>" is the name of the new usage plan. For example, "displayName": "Gold-usage-plan". Avoid entering confidential information.
   • "entitlements": [{...}] specifies details of one or more entitlements, where:
     • "name": "<entitlement-name>" is the name of a new entitlement. Entitlement names must be unique within a usage plan. For example, "Entitlement1". Avoid entering confidential information.
     • "description": "<entitlement-description>" is a description of the new entitlement. For example, "description": "Basic entitlement for all usage plans". Avoid entering confidential information..
     • "rateLimit": {…} optionally specifies a maximum number of requests to allow per second. If you define a rate limit, you must include values for all of the following:
       • "value": <rate-limit-value> is the maximum number of requests to allow. For example, "value": 100.
       • "unit": "<rate-limit-unit>" is the rate limit's unit of time. Must be set to "SECOND".
     • "quota": {…} optionally specifies a maximum number of requests to allow in a given time period. If you define a quota, you must include values for all of the following:
       • "value": <quota-value> is the maximum number of requests to allow per time period. For example, "value": 1000
       • "unit": "<quota-unit>" is the time period to which the maximum number of requests applies. Must be set to one of MINUTE, HOUR, DAY, WEEK, or MONTH. For example, "unit": "MONTH".
       • "resetPolicy": "CALENDAR" is when the count of the number of requests is reset to zero. The CALENDAR reset policy is supported. With the CALENDAR reset policy, the request number count is reset to zero at the start of each new time period, as specified by "unit".

         For example, if "unit": "DAY", the request number count is initially set to zero when the entitlement is first created. The count is then reset to zero at the start of the following day (that is, at midnight UTC). The count is reset to zero at the start of the next day, and so on.

       • "operationOnBreach": "<REJECT|ALLOW>" specifies what happens if the maximum number of requests in the quota's time period is exceeded. If you specify REJECT, additional requests in the time period are rejected and return an HTTP-429 Too Many Requests response. The response includes the Retry-After header, indicating how long to wait before making a new request. If you specify ALLOW, additional requests in the time period are still allowed. For example, "operationOnBreach": "REJECT"
     • "targets": [{…}] specifies one or more target API deployments that subscribers to the usage plan are entitled to access, where:
       • "deploymentId": "<target-deployment-ocid>" is the OCID of the API deployment that you want to include in the entitlement. The API deployment can belong to the same compartment as the usage plan, but does not have to. For example, "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaab______pwa"

         Note that you must have already made the API deployment eligible for inclusion in the usage plan by specifying the location of a client token (see Making an API Deployment Eligible for Inclusion in a Usage Plan).

   • "compartmentId": "<compartment-ocid>" is the OCID of the compartment to which the new usage plan belongs. For example, "ocid1.compartment.oc1..aaaaaaaa7______ysq"

   For example:

   {
       "displayName": "Gold-usage-plan",
       "entitlements": [{
           "name": "Entitlement1",
           "description": "Basic entitlement for all usage plans",
           "rateLimit": {
               "value": 100,
               "unit": "SECOND"
           },
           "quota": {
               "value": 1000,
               "unit": "MONTH",
               "resetPolicy": "CALENDAR",
               "operationOnBreach": "REJECT"
           },
           "targets": [{
               "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaab______pwa"
           }]
       },
       {
           "name": "Entitlement2",
           "description": "Gold plan entitlement",
           "rateLimit": {
               "value": 200,
               "unit": "SECOND"
           },
           "quota": {
               "value": 5000,
               "unit": "WEEK",
               "resetPolicy": "CALENDAR",
               "operationOnBreach": "REJECT"
           },
           "targets": [{
               "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaab______pwa"
             },
             {
               "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaac______nxd"
             }
           ]
         }
       ],
       "compartmentId": "ocid1.compartment.oc1..aaaaaaaa7______ysq"
   }

2. Save the usage plan definition file with a name of your choice. For example, gold-usageplan.json
3. Use the usage plan definition file to create a usage plan using the CLI:
   1. Configure your client environment to use the CLI (Configuring Your Client Environment to use the CLI for API Gateway Development).

   2. Open a command prompt and run oci api-gateway usage-plan create to create the usage plan from the usage plan definition file:

      oci api-gateway usage-plan create --from-json file://<usageplan-definition>.json

      where:

      • --from-json file://<usageplan-definition>.json is the file containing the usage plan definition, including a path.

      For example:

      oci api-gateway usage-plan create --from-json file://gold-usageplan.json

      The response to the command includes:

      • The usage plan's OCID, and other details.
      • The lifecycle state (for example, ACTIVE, FAILED).
      • The id of the work request to create the usage plan (details of work requests are available for seven days after completion, cancellation, or failure).

      If you want the command to wait to return control until the usage plan is active (or the request has failed), include either or both the following parameters:

      • --wait-for-state ACTIVE
      • --wait-for-state FAILED

      For example:

      oci api-gateway usage-plan create --from-json file://gold-usageplan.json --wait-for-state ACTIVE

      Note that you cannot use the usage plan until the work request has successfully created it and the usage plan is active.

   3. (Optional) To see the status of the usage plan, enter:

      oci api-gateway usage-plan get --usage-plan-id <usage-plan-ocid>

   4. (Optional) To see the status of the work request that is creating the usage plan, enter:

      oci api-gateway work-request get --work-request-id <work-request-ocid>

   5. (Optional) To view the logs of the work request that is creating the usage plan, enter:

      oci api-gateway work-request-log list --work-request-id <work-request-ocid>

   6. (Optional) If the work request that is creating the usage plan fails and you want to review the error logs, enter:

      oci api-gateway work-request-error --work-request-id <work-request-ocid>

   For more information about using the CLI, see Command Line Interface (CLI). For a complete list of flags and options available for CLI commands, see CLI Help.

For information about using the API and signing requests, see REST API documentation and Security Credentials. For information about SDKs, see SDKs and the CLI.

Use the CreateUsagePlan operation to create a usage plan.