Example: Usage Scenarios of API Scopes
API Provider can restrict the enforcement of policies at the resource-level or method-level for a REST API, and at the operations-level for a SOAP API. This policy enforcement on the resources, methods, or operations of the API will apply in addition to the default enforcement of policies at the global-level and the user-defined enforcement of policies at the API-level.
Consider you have a REST API, for example, PhoneStore API, with a collection of resources and methods.
Resource Name | Resource Path | Supported Methods |
Resource A | /phones/orders | GET |
POST |
Resource B | /phones/orders/{order-id} | GET |
PUT |
DELETE |
Resource C | /phones/orders/{order-id}/paymentdetails | GET |
POST |
In the following section, we demonstrate the application of scopes and the policy enforcement using Resource C: /phones/orders/{order-id}/paymentdetails of the PhoneStore API.
You can create scopes in the PhoneStore API, and define the individual scopes with a specific set of resources, methods, or both.
Scope Name | Applied Resource | Applied Method |
PAYMENT Scope | Resource C: /phones/orders/{order-id}/paymentdetails | |
WRITE Scope | Resource C: /phones/orders/{order-id}/paymentdetails | POST |
Assume you have an API-level policy which enforces an Identify and Authorize Application policy with HTTP Basic Authentication for the PhoneStore API. Now, you might need to have different authentication mechanisms for different methods and resources (collectively, scopes) of the PhoneStore API, depending on the level of access you need.
For example, you might want to enforce an Inbound Authentication - Transport policy with Require HTTP Basic Authentication for the Resource C in PAYMENT Scope to enforce secured access to the data. You might also want to apply an Identify and Authorize Application policy with API Key authentication and Throttling Traffic Optimization policy (with 5 API invocations per minute), in particular, for the POST method of the Resource C in WRITE Scope to enforce a higher-level of secured access and manipulation of the REST data.
API-level / Scope-level Policy | Applied Policies |
API-level Policy | Identify & Authorize policy with HTTP Basic Authentication |
Scope-level Policy for PAYMENT Scope | Identify & Authorize policy |
Scope-level Policy for WRITE Scope | Identify & Authorize policy with API Key Traffic Optimization |
The API Scopes definition looks like this:
API-level / Scope-level Policy | Applied Policies |
API-level Policy | Identify & Authorize policy with HTTP Basic Authentication |
Policy for PAYMENT Scope | Resource C: /phones/orders/{order-id}/paymentdetails Identify & Authorize policy |
Policy for WRITE Scope | Resource C: /phones/orders/{order-id}/paymentdetails Method: POST Identify & Authorize policy with API Key Traffic Optimization |
The precedence of the policy enforcement effective for an API at run-time is as follows:
1. Global Policy Enforcement
2. Method-level Policy Enforcement (REST APIs) -OR- Operation-level Policy Enforcement (SOAP APIs)
3. Resource-level Policy Enforcement (REST APIs)
4. API-level Policy Enforcement
The specific aspect of processing during the handling of an API invocation at run-time in API Gateway can be best understood with the following scenarios:
Scenario A: Invoke GET method on the Resource C: /phones/orders/{order-id}/paymentdetails
![*](chapterTOC_bullet.png)
Global Policy: Not applicable
![*](chapterTOC_bullet.png)
Method-level Policy: Not applicable
![*](chapterTOC_bullet.png)
Resource-level Policy(s): Inbound Authentication - Transport
![*](chapterTOC_bullet.png)
API-level Policy: Identify and Authorize Application policy with HTTP Basic Authentication
As per the precedence of policy enforcement, the Inbound Authentication - Transport at the resource-level and the Identify and Authorize Application policy with HTTP Basic Authentication at the API-level are enforced at run-time.
The effective policy set enforced on the API for the GET method at run-time includes:
![*](chapterTOC_bullet.png)
Inbound Authentication - Transport
![*](chapterTOC_bullet.png)
Identify and Authorize Application policy with HTTP Basic Authentication
Scenario B: Invoke POST method on the Resource C: /phones/orders/{order-id}/paymentdetails in WRITE Scope
![*](chapterTOC_bullet.png)
Global Policy: Not applicable
![*](chapterTOC_bullet.png)
Method-level Policy(s): (1) Identify and Authorize Application policy with API Key (2) Throttling Traffic Optimization
![*](chapterTOC_bullet.png)
Resource-level Policy(s): Inbound Authentication - Transport
![*](chapterTOC_bullet.png)
API-level Policy: Identify and Authorize Application policy with HTTP Basic Authentication
As per the precedence of policy enforcement, the Identify and Authorize Application policy with API Key at the method-level takes precedence over the Identify and Authorize Application policy with HTTP Basic Authentication at the API-level, and is enforced at run-time.
The effective policy set enforced on the API for the POST method at run-time includes:
![*](chapterTOC_bullet.png)
Inbound Authentication - Transport
![*](chapterTOC_bullet.png)
Identify and Authorize Application policy with API Key
![*](chapterTOC_bullet.png)
Throttling Traffic Optimization
Now, consider that you apply an active Global Policy that has the Identify and Authorize Application policy with Hostname Address for all REST APIs (including our PhoneStore API).
Scenario C: Invoke POST method on the Resource C: /phones/orders/{order-id}/paymentdetails in WRITE Scope
![*](chapterTOC_bullet.png)
Global Policy: Identify and Authorize Application policy with Hostname Address
![*](chapterTOC_bullet.png)
Method-level Policy(s): (1) Identify and Authorize Application policy with API Key (2) Throttling Traffic Optimization
![*](chapterTOC_bullet.png)
Resource-level Policy(s): Inbound Authentication - Transport
![*](chapterTOC_bullet.png)
API-level Policy: Identify and Authorize Application policy with HTTP Basic Authentication
As per the precedence of policy enforcement, the Identify and Authorize Application policy with Hostname Address applied through the global policy takes precedence over every other Identify and Authorize Application policy that is applied at the method-level and the API-level, and is enforced at run-time.
The effective policy set enforced on the API for the POST method at run-time includes:
![*](chapterTOC_bullet.png)
Inbound Authentication - Transport
![*](chapterTOC_bullet.png)
Identify and Authorize Application policy with Hostname Address
![*](chapterTOC_bullet.png)
Throttling Traffic Optimization
Resolving Scope Conflicts
When you save an API, API Gateway combines the scopes specified with the set of policies defined at the API-level, and on saving the API, API Gateway applies the policies to the API at various enforcement levels. API Gateway validates the scope list to ensure that it contains no conflicting or incompatible policies. If the list contains conflicts or inconsistencies, API Gateway prompts you with an error message.
Consider that you modify the existing UPDATE scope to include a POST method for Resource C. The API Scopes definition now looks like this:
API-level / Scope-level Policy | Applied Policies |
API-level Policy | Identify & Authorize policy with HTTP Basic Authentication |
Policy for PAYMENT Scope | Resource C: /phones/orders/{order-id}/paymentdetails Identify & Authorize policy |
Policy for WRITE Scope | Resource C: /phones/orders/{order-id}/paymentdetails Method: POST Identify & Authorize policy with API Key Traffic Optimization |
Policy for UPDATE Scope | Resource C: /phones/orders/{order-id}/paymentdetails Method: POST Identify & Authorize policy with API Key |
Scenario D: Save the updated PhoneStore API.
![*](chapterTOC_bullet.png)
Global Policy: Not applicable
![*](chapterTOC_bullet.png)
Method-level Policy(s): (1) Identify and Authorize Application policy with API Key (2) Identify and Authorize Application policy with IP Address Range (3) Throttling Traffic Optimization
![*](chapterTOC_bullet.png)
Resource-level Policy(s): Inbound Authentication - Transport
![*](chapterTOC_bullet.png)
API-level Policy: Identify and Authorize Application policy with HTTP Basic Authentication
As per the precedence of policy enforcement, the Identify and Authorize Application policy at the method-level in WRITE and UPDATE Scopes take precedence over the Identify and Authorize Application policy at the API-level. But the Identify and Authorize Application policy with the API Key and IP Address Range authentications that are applied at the method-level results in a policy conflict.
To resolve the conflicts, you can choose one of the following workaround:
Option 1: Remove the existing association between the POST method and the WRITE Scope or UPDATE Scope through the API Scope details.
Option 2: Delete the WRITE Scope or UPDATE Scope.
Option 3: Remove the Identify and Authorize Application policy from the WRITE Scope or UPDATE Scope.