Making an API Deployment Eligible for Inclusion in a Usage Plan

To make an API deployment eligible for inclusion in a usage plan, you have to specify the location of a client token passed in a request. To specify the location for the client token by adding a usage plan request policy to an API deployment specification using the Console:

1. Create or update an API deployment using the Console, select the From Scratch option, and enter details on the Basic Information page.

   For more information, see Deploying an API on an API Gateway by Creating an API Deployment and Updating an API Gateway or an API Deployment.

2. In the API Request Policies section of the Basic Information page, click the Add button beside Usage Plan and specify:

   • Token Location: The location of a client token that subscribed API clients must include in their requests in the format <context-table-name>[<client-token-location-name>], where:
     • <context-table-name> is one of request.path, request.query, request.headers, request.auth or request.host, depending on how you want API clients to pass the client token when making requests.
     • <client-token-location-name> is a name of your choice for the client token location (for example, client-id, client-token, my-token). Not applicable for request.host.

     For example, request.headers[client-id]

3. Click Save Changes, and then click Next to enter details for individual routes in the API deployment on the Routes page. Note that you cannot apply usage plan request policies to individual routes in the API deployment specification.

4. Click Next to review the details you entered for the API deployment.
5. Click Create or Save Changes to create or update the API deployment.
6. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an API Deployed on an API Gateway).

To make an API deployment eligible for inclusion in a usage plan, you have to specify the location of a client token passed in a request. To specify the location for the client token by adding a usage plan request policy to an API deployment specification in a JSON file:

1. Using your preferred JSON editor, edit the existing API deployment specification to which you want to add a usage plan request policy, or create a new API deployment specification (see Creating an API Deployment Specification).

   For example, the following basic API deployment specification defines a simple Hello World serverless function in OCI Functions as a single back end:

   {
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

2. Insert a requestPolicies section before the routes section, if one doesn't exist already. For example:

   {
     "requestPolicies": {},													
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

3. Add the following usagePlans policy to the new requestPolicies section to apply to all routes defined in the specification:

   {
     "requestPolicies": {
       "usagePlans": {
         "tokenLocations": ["<context-table-name>[<client-token-location-name>]"]
       }
     },													
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

   where:

   • <context-table-name> is one of request.path, request.query, request.headers, request.auth, or request.host, depending on how you want API clients to pass the client token when making requests.
   • <client-token-location-name> is a name of your choice for the client token location (for example, client-id, client-token, my-token). Not applicable for request.host.

   Note that for any given usage plan, you can only specify one client token location.

   For example:

   {
     "requestPolicies": {
       "usagePlans": {
         "tokenLocations": ["request.headers[client-id]"]
       }
     },													
     "routes": [
       {
         "path": "/hello",
         "methods": ["GET"],
         "backend": {
           "type": "ORACLE_FUNCTIONS_BACKEND",
           "functionId": "ocid1.fnfunc.oc1.phx.aaaaaaaaab______xmq"
         }
       }
     ]
   }

4. Save the JSON file containing the API deployment specification.

5. Use the API deployment specification when you create or update an API deployment in the following ways:

   • by specifying the JSON file in the Console when you select the Upload an existing API option
   • by specifying the JSON file in a request to the API Gateway REST API

   For more information, see Deploying an API on an API Gateway by Creating an API Deployment and Updating an API Gateway or an API Deployment.

6. (Optional) Confirm the API has been deployed successfully by calling it (see Calling an API Deployed on an API Gateway).