Example - Usage scenarios of API scopes

Consider you have a REST API, for example, PhoneStore API, with a collection of resources and methods.

The following example demonstrates the application of scopes and the policy enforcement by using Resource C: /phones/orders//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.

Assume that 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 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.

The API Scopes definition looks like this:

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//paymentdetails

• Global Policy - Not applicable
• Method-level Policy - Not applicable
• Resource-level Policies - Inbound Authentication - Transport
• API-level Policy - Identify and Authorize Application policy with HTTP Basic Authentication

According to 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 the following policies.

• Inbound Authentication - Transport
• Identify and Authorize Application policy with HTTP Basic Authentication

Scenario B - Invoke POST method on the Resource C: /phones/orders//paymentdetails in WRITE Scope

• Global Policy - Not applicable
• Method-level Policies - (1) Identify and Authorize Application policy with API Key (2) Traffic Optimization
• Resource-level Policies - Inbound Authentication - Transport
• API-level Policy - Identify and Authorize Application policy with HTTP Basic Authentication

According to 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 the following policies.

• Inbound Authentication - Transport
• Identify and Authorize policy with API Key
• Traffic Optimization

Now, consider that you apply an active Global Policy that has the Identify and Authorize policy with Hostname Address for all REST APIs that includes the PhoneStore API.

Scenario C - Invoke POST method on the Resource C: /phones/orders//paymentdetails in WRITE Scope

• Global Policy - Identify and Authorize Application policy with Hostname Address
• Method-level PolicyIdentify and Authorize policy with API Key
  1. Traffic Optimization
• Resource-level Policies - Inbound Authentication - Transport
• API-level Policy - Identify and Authorize policy with HTTP Basic Authentication

According to the precedence of policy enforcement, the Identify and Authorize policy with Hostname Address that is 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 the following policies.

• Inbound Authentication - Transport
• Identify and Authorize policy with Hostname Address
• Traffic Optimization

Resolving Scope Conflicts

When you save an API, webMethods API Gateway combines the scopes that are specified with the set of policies that are defined at the API-level, and on saving the API, webMethods API Gateway applies the policies to the API at various enforcement levels. webMethods 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.

Scenario D - Save the updated PhoneStore API.

• Global Policy - Not applicable.
• Method-level Policies
  1. Identify and Authorize policy with API Key
  2. Identify and Authorize policy with IP Address Range
  3. Traffic Optimization
• Resource-level Policies - Inbound Authentication - Transport
• API-level Policy - Identify and Authorize policy with HTTP Basic Authentication

According to the precedence of policy enforcement, the Identify and Authorize Application policy at the method-level in WRITE and UPDATE Scopes takes 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 workarounds

• 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.