3.31. Set Global Configurations

DigitMarket™ API Manager allows you to set global configurations from its Global Configuration menu. Configurations that the user can set include:

• Publisher portal environment settings, such as options to show or hide Sandbox environment and renaming the Production environment
• Approval workflows for APIs, API Packs, Usage Plans and Usage Policies
• Default fault codes and fault messages for SOAP and REST API errors

Common Tasks

Following common task is identified for this section:

• Navigating to the Global Configuration screen

  To navigate to the Global Configuration screen:

  • In the main navigation menu, click Global Configuration.

  

  Fig. 3.559 Navigation menu - Global Configuration

  The Global Configuration screen displays.

  

  Fig. 3.560 Global Configuration screen

3.31.1. Configuring Environment Settings

To configure Environment settings:

1. Navigate to the Global Configuration screen.

2. Click the Settings tab to display the Environment settings screen.

   

   Fig. 3.561 Settings tab

3. In Primary Environment, in the Edit Environment Name box, type a new name for the Production environment name if you want to name the default name of ‘Production’ to any other name of your choice. Doing this changes the environment name in the Endpoints tab of the API Configuration screen.

   

   Fig. 3.562 Edit Environment Name

4. In Sandbox Environment, click to uncheck the Display Sandbox section check box, which is checked by default, to stop displaying the Sandbox section in the Endpoints tab of the API Configuration screen.

5. In Sandbox Environment, in the Sandbox Endpoint Basepath box, type/edit the base path for the Endpoint used for the Sandbox environment.

   

   Fig. 3.563 Edit Environment Name

6. Click Submit to save changes.

3.31.2. Configuring Approval Workflows

Approval workflows allow the user to configure whether or not an artifact, i.e., APIs, API Packs, Usage Plans, and Usage Policies will require approval to advance to the next state in the artifact life cycle. If the automatic approval workflow is enabled, the artifact will not require an approval and the artifact progresses to the next state in the life cycle automatically. On the other hand, if approval workflow is not set to automatic, each state of the artifact life cycle will require approval to advance to the next state in its life cycle.

Refer Life cycle of Artifacts and Approval Workflows to learn more about artifact life cycle.

Refer Manage Approvals for more information about managing approvals.

To configure workflows for approvals:

1. Navigate to the Global Configuration screen.

2. Click the Settings tab to display the Environment settings screen.

3. In the Configure WorkFlows section, drag the slider to enable/disable approvals for Admin/Approver/Business users for artifacts APIs/API Packs/Usage Plans/Usage Policies.

   The slider is turned off and displays red by default. Moving the slider to the right turns the slider toggle state to green for a corresponding user and artifact. You can toggle states; green to allow automatic approval and red to disable automatic approval workflow.

   

   Fig. 3.564 Enable/disable approvals

4. Click Submit to save changes.

3.31.3. Setting Fault Configuration

Errors or Faults can occur during the invocation of API calls. The kind of errors that the client can encounter vary from failed authentication to errors resulting from badly formed messages. Returning the error data can help client applications identify and resolve runtime errors.

DigitMarket™ API Manager allows the user to customize the fault configuration for gateway faults. A publisher organization can have the fault structure configured at a global level. This fault configuration, in turn, will be mimicked by each Gateway of the publisher organization. When you save and propagate changes in the fault configuration, the changes are made operational in each Gateway.

Note

If the organization has multiple Gateways, modifications can be made at Global Configuration. The changes will be reflected in all the Gateways present in the sub-organization if the gateway isn’t overridden. All the Gateways needs to be propagated.

In the event of an error at runtime, the Gateway returns the saved fault codes and messages to the user’s machines.

DigitMarket™ API Manager allows the user to set the fault configuration for gateway faults for REST and SOAP services at:

• Gateway Level
• Plan Level
• Resource/Operation Level

Note

Default Fault Configuration for a Publisher organization is configured at Global Level.

Gateway Level

Gateway level fault configuration can be configured at Global Level. Each and every Gateway can configure its own fault configuration. Publisher organizations having more than one Gateway can configure fault configuration at one Gateway and the same can be propagated to other Gateways. Gateway level fault configuration can be overridden at each Gateway. Gateway level scenarios be overridden only at Global level and Gateway level.

Plan Level

Plan level fault configuration can be configured at Global Level. This is applicable to all Gateways of the organization. It can be overridden at Gateway level for each Gateway, Plan level fault configuration can be configured at Global Level. This is applicable to all Gateways of the organization. It can be overridden at Gateway level for each Gateway, Plan level and at Subscription level.

Plan level Fault configuration (Fault Structure/Content-Type/Fault Message) precedence hierarchy is: Subscription level > Plan level > Gateway level

Resource Level

Resource/Operation level fault configuration can be configured at Global Level. This is applicable to all Gateways of the organization. When creating a new API version the Gateway level fault configuration will be applicable on all the resources/operations of the API, but it can be overridden at API Version level and for each API resource/operation. It can also be overridden at plan level for all/each plan(s) and at subscription level for all/each resource(s)/operation(s) of the subscription.

When adding a resource to a plan, the fault configuration from the API version resource/operation will be applicable, but it can be overridden at plan resource/operation level for all/each resource(s)/operation(s) of the plan.

Note

A Resource that is not in a plan will be of no use as this will always lead to an unauthorized request scenario.

When a subscription for a plan is created and published, the fault configuration from plan resource/operation level will be applicable for the subscription resource/operation fault configuration, but it can be overridden at subscription level for all/each resource(s)/operation(s) of the subscription.

Resource/Operation level fault configuration (Fault Structure/Content-Type/Fault Message) precedence hierarchy is: Subscription level for each resource > Subscription level for all resources > Plan level for each resource > Plan level for all resources > API Version level for each resource > API Version level for all resources > Gateway level configuration

Setting up the fault configuration in DigitMarket™ API Manager invloves configuring Fault Content Type, Fault Structure and Fault Message.

Fault Content Type

Fault content type defines the format in which the fault structure will be returned. For REST services, you can define the content type in JSON, XML and Plain Text. Fault content type can be configured at Gateway Level, Plan Level and Resource Level. If not overwritten, the default fault configuration will be sent as a response. Content type for SOAP is by default is XML, hence the fault response will be returned in XML.

Fault Content Type precedence hierarchy is: Accept header > Content-Type header > Payload type > Configured value

Fault Structure

Fault structure is the template/schema that will return the errors for various gateway faults. This fault template will be used to display the fault response. For REST services, you can define the fault template in JSON, XML and Plain Text. Fault structure can be configured at Gateway Level, Plan Level and Resource Level. If not overwritten, the default fault configuration will be sent as a response. For SOAP services, you can define the fault template only in XML.

The fault structure can be overridden at API Version level, Resource/Operation level, Plan level for all/each Resource, Subscription level for all/each Resources. The overwritten fault structures will be picked only if the Allow override has been selected under the Select Fault Template dropdown in Gateway fault configuration for each Plan level and Resource level fault scenarios.

Fault Message

Fault Messages are a list of fault scenarios with corresponding Response Codes, HTTP Codes and Fault Message Content. Based on the fault scenario and the content type you select, the appropriate fault message content will be delivered to the user’s machine. Response Code, HTTP Code and the Fault Message Content for a fault scenario are configurable for both REST and SOAP fault errors.

3.31.3.1. Setting Fault Configuration for REST APIs

You can configure the fault structure template, content type and fault messages for Gateway faults for REST APIs. You can configure a default fault configuration at Global Level, and you can overwrite that default fault configuration at Gateway level, API Version level, Plan level, Operation level and Subscription level.

To set the Default REST Fault Configuration at Global Level:

1. Navigate to the Global Configuration page.

2. Click the Fault Configuration tab and then click the REST sub-tab to open the Default Fault Configuration section.

   

   Fig. 3.565 Fault Configuration for REST

3. Click to expand the Default Content Type accordion tab. At Global Level, you can configure the Default Content Type for Gateway/Plan/Resource Level in JSON/XML/PlainText.

   

   Fig. 3.566 Default Content Type

4. Click to select the required Content Type (JSON/XML/PlainText) option to be configured at Gateway/Plan/Resource level and click Save to save the changes.

5. Next, click to expand the Default Fault Structure accordion tab. At Global Level, you can configure the Default Fault Structure for Gateway/Plan/Resource Level in JSON/XML/PlainText.

   

   Fig. 3.567 Default Fault Structure

6. (Optional) Edit the JSON/XML/PlainText Fault box to make any required changes to the Default Fault Structure at Gateway/Plan/Resource Level and then click Save to save the changes.

7. Next, click to expand the Scenario-wise Fault Message accordion tab. At Global Level, you can configure the Default Fault Message for Gateway/Plan/Resource Level in JSON/XML/PlainText.

   

   Fig. 3.568 Default Fault Message

8. (Optional) Click the Response Code box corresponding to the Fault scenario to type in a different fault code in the box.

9. (Optional) Click the HTTP Code box corresponding to the Fault scenario to type in a different HTTP code in the box.

10. (Optional) Click the Fault Message Content box corresponding to the Fault scenario to type in a different Fault Message in the box.

11. Click Save to save the changes.

12. Click Close to exit the Fault Configuration window.

13. After any changes in the Fault configuration at Gateway/Global configuration, gateway needs to be re-propagated.

To set the REST Fault Configuration at Gateway Level:

1. Navigate to the Gateways page.

2. Click the Fault Configuration icon and then click the REST tab to open the Gateway Fault Configuration window.

   

   Fig. 3.569 Gateway Fault Configuration

3. Click to expand the Default Content Type accordion tab. At Gateway Level, you can overwrite the Gateway/Plan/Resource Level Content Type that was configured at Global level. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the Default Content Type settings. Upon enabling Overwrite, the Content Type options for Gateway/Plan/Resource level will be enabled.

   

   Fig. 3.570 Gateway Content Type

4. Click the required Content Type (JSON/XML/PlainText) option to select to be configured at Gateway/Plan/Resource Level and then click Save.

5. Next, click to expand the Fault Structure accordion tab. At Gateway Level, you can overwrite the Gateway/Plan/Resource Level Fault Structure that was configured at Global level. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the Default Fault Structure settings. Upon enabling Overwrite, the Fault Structure options for Gateway/Plan/Resource level will be enabled.

   

   Fig. 3.571 Gateway Fault Structure

6. (Optional) Edit the JSON/XML/PlainText Fault box to make any required changes to the Fault template at Gateway/Plan/Resource Level and then click Save to save the changes.

7. Next, click to expand the Scenario-wise Fault Message accordion tab. At Gateway Level, you can overwrite the Gateway/Plan/Resource Level Fault Message that was configured at Global level. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the default Fault Message settings. Upon enabling Overwrite, the Fault Message options for Gateway/Plan/Resource level will be enabled.

   

   Fig. 3.572 Scenario-wise Fault Message

8. (Optional) Click the Response Code box corresponding to the Fault scenario to type in a different fault code in the box.

9. (Optional) Click the HTTP Code box corresponding to the Fault scenario to type in a different HTTP code in the box.

10. (Optional) Click the Fault Message Content box corresponding to the Fault scenario to type in a different Fault Message in the box.

11. Click Save. This will overwrite the default Fault Message settings.

12. Click Close to exit the Fault Configuration window.

13. After any changes in the Fault configuration at Gateway/Global configuration, gateway needs to be re-propagated.

To set the REST Fault Configuration at API Version Level:

1. Navigate to the REST API Configuration page.

2. Click Advanced tab and then click REST Fault Configuration tab.

   

   Fig. 3.573 REST Fault Configuration

3. Click to expand the Default Content Type accordion tab. You can overwrite the configured Content Type at API Version Level and for each Resource. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the default Content Type settings. Upon enabling Overwrite, the Content Type options at Version Level and for each Resource will be enabled.

   

   Fig. 3.574 Default Content Type

4. Click to select the required Content Type (JSON/XML/PlainText) option to be configured at API Version Level and for each Resource and then click Save. This will overwrite the Default Content Type settings.

5. Next, click to expand the Fault Structure accordion tab. You can overwrite the configured Fault Structure at API Version Level and for each Resource. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the default Fault Structure settings. Upon enabling Overwrite, the Fault Structure options at Version Level and for each Resource will be enabled.

   

   Fig. 3.575 Fault Structure

6. (Optional) Edit the JSON/XML/PlainText Fault box to make any required changes to the Fault template at API Version Level and for each Resource and then click Save to save the changes.

7. Next, click to expand the Scenario-wise Fault Message accordion tab. You can overwrite the configured Fault Message at API Version Level and for each Resource. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the default Fault Message settings. Upon enabling Overwrite, the Fault Message options at Version Level and for each Resource will be enabled.

   

   Fig. 3.576 Fault Message

8. (Optional) Click the Response Code box corresponding to the Fault scenario to type in a different fault code in the box.

9. (Optional) Click the HTTP Code box corresponding to the Fault scenario to type in a different HTTP code in the box.

10. (Optional) Click the Fault Message Content box corresponding to the Fault scenario to type in a different Fault Message in the box.

11. Click Save. This will overwrite the default Fault Message settings.

12. Click Close to exit the Fault Configuration window.

To set the REST Fault Configuration at Plan Level:

1. Navigate to the REST API Configuration page.

2. Click Usage Plans tab and then click the Plan Name.

   

   Fig. 3.577 Fault Configuration

Note

Fault configuration can be set only for Plans in Draft state.

3. Click Fault Configuration accordion tab and then click Content Type. You can overwrite the configured Content Type at Plan level and for all/individual Resources. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the default Content Type settings. Upon enabling Overwrite, the Content Type options at Plan Level and for all/individual Resources will be enabled.

   

   Fig. 3.578 Content Type

4. Click to select the required Content Type (JSON/XML/PlainText) option to be configured at Plan Level and for each all/individual Resources and then click Save as Draft. This will overwrite the default Content Type settings.

5. Next, click Fault Structure accordian tab. You can overwrite the configured Fault Structure at Plan level and for all/individual Resources. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the default Fault Structure settings. Upon enabling Overwrite, the Fault Structure options at Plan Level and for all/individual Resources will be enabled.

   

   Fig. 3.579 Fault Structure

6. (Optional) Edit the JSON/XML/PlainText Fault box to make any required changes to the Fault template at Plan Level and for all/individual Resources and then click Save as Draft to save the changes.

7. Next, click Scenario-wise Fault Message. You can overwrite the configured Fault Message at Plan Level and for all/individual Resources. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the default Fault Message settings. Upon enabling Overwrite, the Fault Message options at Plan Level and for all/individual resources will be enabled.

   Note

   If Fault Configuration is overwritten for All Resources of a Plan, then the fault configuration of All Resources will be applicable for each Resource.

   

   Fig. 3.580 Fault Message

8. (Optional) Click the Response Code box corresponding to the Fault scenario to type in a different fault code in the box.

9. (Optional) Click the HTTP Code box corresponding to the Fault scenario to type in a different HTTP code in the box.

10. (Optional) Click the Fault Message Content box corresponding to the Fault scenario to type in a different Fault Message in the box.

11. Click Save as Draft. This will overwrite the default Fault Message settings.

To set the REST Fault Configuration at Subscription Level:

1. Navigate to the Subscriptions page.

2. Click on a REST pack to select it and then click Settings sub-tab.

3. Scroll down to the Fault Configuration section.

   

   Fig. 3.581 Fault Configuration

Note

Fault configuration can be set only for active subscriptions.

4. Under Fault Configuration section, click Content Type tab. You can overwrite the configured Content Type at Plan Level and for all/individual Resources. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the default Content Type settings. Upon enabling Overwrite, the Content Type options at Plan Level and for all/individual Resources will be enabled.

   

   Fig. 3.582 Content Type

5. Click to select the required Content Type JSON/XML/PlainText to be configured at Plan Level and for each all/individual Resources and then click Submit. This will overwrite the default Content Type settings.

6. Next, click Fault Structure tab. You can overwrite the configured Fault Structure at Plan level and for all/individual Resources. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the default Fault Structure settings. Upon enabling Overwrite, the Fault Structure options at Plan Level and for all/individual Resources will be enabled.

   

   Fig. 3.583 Fault Structure

7. (Optional) Edit the JSON/XML/Plain Text Fault box to make any required changes to the Fault template at Plan level and for all/individual resources and then click Submit to save the changes.

8. Next, click Fault Message. You can overwrite the configured Fault Message at Plan level and for all/individual resources. Move the toggler to the right to activate overwrite and do the inverse to retain the default Fault Message settings. Upon enabling Overwrite, the Fault Message options at Plan Level and for all/individual Resources will be enabled.

   Note

   If Fault Configuration is overwritten for All Resources of a Subscription, then the fault configuration of All Resources will be applicable for each Resource.

   

   Fig. 3.584 Fault Message

9. (Optional) Click the Response Code box corresponding to the Fault scenario to type in a different fault code in the box.

10. (Optional) Click the HTTP Code box corresponding to the Fault scenario to type in a different HTTP code in the box.

11. (Optional) Click the Fault Message Content box corresponding to the Fault scenario to type in a different Fault Message in the box.

12. Click Submit. This will overwrite the default Fault Message settings.

3.31.3.2. Setting Fault Configuration for SOAP APIs

DMAPIM allows the user to configure the fault structure template and fault messages for gateway faults for SOAP APIs. You can configure a default fault configuration at Global Level, and you can overwrite that default fault configuration at Gateway level, API Version level, Plan level, Operation level and Subscription level.

To set the Default SOAP Fault Configuration at Global Level:

1. Navigate to the Global Configuration page.

2. Click the Fault Configuration tab and then click the SOAP sub-tab to open the Default Fault Configuration section.

   

   Fig. 3.585 Default Fault Configuration

3. Click to expand the Default Fault Structure accordion tab. At Global Level, you can configure the Default Fault Structure for Gateway/Plan/Resource Level in XML.

   

   Fig. 3.586 Default Fault Structure

4. (Optional) Edit the XML Fault box to make any required changes to the Default Fault Structure at Gateway/Plan/Resource Level and then click Save to save the changes.

5. Next, click to expand the Default Scenario-wise Fault Message accordion tab. At Global Level, you can configure the Default Fault Message for Gateway/Plan/Resource Level in XML.

   

   Fig. 3.587 Enable/disable approvals

6. (Optional) Click the Response Code box corresponding to the Fault scenario to type in a different fault code in the box.

7. (Optional) Click the HTTP Code box corresponding to the Fault scenario to type in a different HTTP code in the box.

8. (Optional) Click the Fault Message Content box corresponding to the Fault scenario to type in a different Fault Message in the box.

9. Click Save to save the changes.

10. If user updates fault configuration (Content type/Fault structure /fault message) at any level or at for any artifact then the respective artifact needs to be repropagted.

To set the SOAP Fault Configuration at Gateway Level:

1. Navigate to the Gateways page.

2. Click the Fault Configuration icon and then click the SOAP tab to open the Gateway Fault Configuration window.

   

   Fig. 3.588 Fault Configuration

3. Click to expand the Fault Structure accordion tab. At Gateway level, you can overwrite the Gateway/Plan/Operation level Fault Structure that was configured at Global level. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the Default Fault Structure settings. Upon enabling Overwrite, the Fault Structure options for Gateway/Plan/Operation level will be enabled.

   

   Fig. 3.589 Fault Structure

4. (Optional) Edit the XML Fault box to make any required changes to the Fault template at Gateway/Plan/Operation Level and then click Save to save the changes.

5. Next, click to expand the Scenario-wise Fault Message accordion tab. At Gateway level, you can overwrite the Gateway/Plan/Operation level Fault Message that was configured at Global level. Move the toggler to the right to activate Overwrite and do the inverse to retain the Default Fault Message settings. Upon enabling Overwrite, the Fault Message options for Gateway/Plan/Operation level will be enabled.

   

   Fig. 3.590 Fault Message

6. (Optional) Click the Response Code box corresponding to the Fault scenario to type in a different fault code in the box.

7. (Optional) Click the HTTP Code box corresponding to the Fault scenario to type in a different HTTP code in the box.

8. (Optional) Click the Fault Message Content box corresponding to the Fault scenario to type in a different Fault Message in the box.

9. Click Save. This will overwrite the default Fault Message settings.

10. Click Close to exit the Fault Configuration window.

To set the SOAP Fault Configuration at API Version Level

1. Navigate to the SOAP API Configuration page.

2. Click Advanced tab and then click SOAP Fault Configuration tab.

   

   Fig. 3.591 SOAP Fault Configuration

3. Click to expand the Fault Structure accordion tab. You can overwrite the configured Fault Structure at Version level and for each Operation. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the default Fault Structure settings. Upon enabling Overwrite, the Fault Structure options at Version level and for each Operation will be enabled.

   

   Fig. 3.592 Fault Structure

4. (Optional) Edit the XML Fault box to make any required changes to the Fault template at API Version Level and for each Operation and then click Save as Draft to save the changes.

5. Next, click to expand the Scenario-wise Fault Message accordion tab. You can overwrite the configured Fault Message at Version level and for each Operation. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the Default Fault Message settings. Upon enabling Overwrite, the Fault Message options at Version Level and for each Operation will be enabled.

   

   Fig. 3.593 Fault Message

6. (Optional) Click the Response Code box corresponding to the Fault scenario to type in a different fault code in the box.

7. (Optional) Click the HTTP Code box corresponding to the Fault scenario to type in a different HTTP code in the box.

8. (Optional) Click the Fault Message Content box corresponding to the Fault scenario to type in a different Fault Message in the box.

9. Click Save as Draft. This will overwrite the Default Fault Message settings.

To set the SOAP Fault Configuration at Plan Level:

1. Navigate to the SOAP API Configuration page.
2. Click Usage Plans tab and then click the Plan Name.

Note

Fault configuration can be set only for Plans in Draft state.

3. Click Fault Config accordion tab and then click Fault Structure. You can overwrite the configured Fault Structure at Plan level and for all/individual Operations. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the Default Fault Structure settings. Upon enabling Overwrite, the Fault Structure options for Plan and for all/individual Operations will be enabled.

   

   Fig. 3.594 Fault Structure

4. (Optional) Edit the XML Fault box to make any required changes to the Fault template at Plan level and for all/individual Operations and then click Save as Draft to save the changes.

5. Next, click Scenario-wise Fault Message. You can overwrite the configured Fault Message at Plan level and for all/individual Operations. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the default Fault Message settings. Upon enabling Overwrite, the Fault Message options at Plan level and for all/individual Operations will be enabled.

   Note

   If Fault Configuration is overwritten for All Operations of a Plan, then the fault configuration of All Operations will be applicable on each Operation.

   

   Fig. 3.595 Fault Message

6. (Optional) Click the Response Code box corresponding to the Fault scenario to type in a different fault code in the box.

7. (Optional) Click the HTTP Code box corresponding to the Fault scenario to type in a different HTTP code in the box.

8. (Optional) Click the Fault Message Content box corresponding to the Fault scenario to type in a different Fault Message in the box.

9. Click Save as Draft. This will overwrite the default Fault Message settings.

To set the SOAP Fault Configuration at Subscription Level:

1. Navigate to the Subscriptions page.

2. Click on a SOAP pack to select it and then click Settings sub-tab.

3. Scroll down to the Fault Configuration section.

   

   Fig. 3.596 Fault Configuration

Note

Fault configuration can be set only for active subscriptions.

4. Under Fault Configuration section, click Fault Structure. You can overwrite the configured Fault Structure at Plan level and for all/individual operations. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the default Fault Structure settings.

   

   Fig. 3.597 Fault Structure

5. (Optional) Edit the XML Fault box to make any required changes to the Fault template at Plan level and for all/individual Operations and then click Submit to save the changes.

6. Next, click Scenario-wise Fault Message tab. You can overwrite the configured Fault Message at Plan level and for all/individual Operations. Move the Overwrite toggler to the right to activate overwrite and do the inverse to retain the default Fault Message settings. Upon enabling Overwrite, the Fault Message options at Plan level and for all/individual Operations will be enabled.

   Note

   If Fault Configuration is overwritten for All Operations of a Subscription, then the fault configuration of All Operations will be applicable on each Operation.

   

   Fig. 3.598 Fault Message

7. (Optional) Click the Response Code box corresponding to the Fault scenario to type in a different fault code in the box.

8. (Optional) Click the HTTP Code box corresponding to the Fault scenario to type in a different HTTP code in the box.

9. (Optional) Click the Fault Message Content box corresponding to the Fault scenario to type in a different Fault Message in the box.

10. Click Submit. This will overwrite the default Fault Message settings.

3.31.4. Macros for Fault Structure

The tables below provide lists of macros that can be used for the default level and resource level fault structures.

Table 3.22 Gateway and Plan level fault structure macros (JSON, XML and Plain Text)

Macro	Description
XXXREQIDXXX	Prints the Request-ID/SOA-Transaction-ID
XXXSOAFAULTORGINXXX	Prints the fault origin
XXXSOAFAULTCODEXXX	Prints the fault code
XXXFAULTDESCXXX	Prints the fault description

Table 3.23 Resource/Operation level fault structure macros (JSON, XML and Plain Text)

Macro	Description
XXXREQIDXXX	Prints the Request-ID/SOA-Transaction-ID
XXXSOAFAULTORGINXXX	Prints the fault origin
XXXSOAFAULTCODEXXX	Prints the fault code
XXXFAULTDESCXXX	Prints the fault description
XXXOPNAMEXXX	Prints the operation name

3.31.5. Configuration Scenarios

Configuration Scenarios detail the scenarios encountered in the gateway during the request and response processing. As seen above, the user can configure the response code, and other details for SOAP and REST faults/errors separately.

The following are the list of Gateway level scenarios specific to REST:

1. Invalid client IP

   The Gateway processes only those requests that come through the reverse proxy server. This IP is passed as an argument during gateway start-up. This scenario occurs when any request is received from a different IP or directly from the client.

   
   

2. Invalid Subscription Key

   The Gateway occurs this scenario for the below use cases:

   1. When APIC-Subs-Key/DMAPIM-Subs-Key header is not present
   2. Subscription key value is not present
   3. Subscription key value not existing in the portal
   
   

3. OAuth Plugin Unavailable

   This error scenario can occur only for the below mentioned use cases:

   1. If the path specified for the OAuth Plugin is wrong.
   2. If there is no read permission for the OAuth Plugin jar.
   3. If an OAuth related request is received when the OAuth plugin is disabled.

4. OAuth Server Unavailable

   This error scenario occurs when the OAuth server is not reachable.

   
   

5. OAuth Server Request Timeout

   This error scenario occurs when the OAuth server is reachable but does not respond within the configured request timeout.

   
   

6. OAuth Plugin Error

   This error scenario occurs when an error occurs inside the gateway OAuth plugin during execution.

7. Invalid OAuth Request URL

   This error scenario occurs when the basepath starts with OAuth and the remaining part of the URL doesnot match with any of OAuth URLs.

8. Empty Request Body

   This scenario occurs when the request does not contain the request body (for POST/PUT/DELETE/PATCH requests).

   
   

9. Invalid Request body

   This scenario occurs when the request has a request body that is not valid(for POST/PUT/DELETE/PATCH requests).

   
   

The following are the list of Gateway level scenarios specific to SOAP:

1. Invalid client IP

   The Gateway processes only those requests that come through the reverse proxy server. This IP is passed as an argument during gateway start-up. This scenario occurs when any request is received from a different IP or directly from the client.

   
   

2. Invalid Subscription Key

   The Gateway occurs this scenario for the below use cases:

   1. When APIC-Subs-Key header is not present
   2. Subscription key value is not present
   3. Subscription key value not existing in the portal
   
   

3. WSDL Not found

   This error scenario can only occur when the corresponding WSDL is not found for a WSDL download request.

   
   

4. Gateway Configuration Error

   This scenario occurs when the request have the below use cases:

   1. When plan_resources_cache is empty.
   2. When the plan_resource cache does not have any value for the plan_id mentioned in subscription_details table.
   3. When Subscriber_level_policies does not have any values for the subscription ID mentioned in subscription table.
   
   

5. Empty Request Body

   This scenario occurs when the request does not contain the request body.

   
   

6. Invalid Request body

   This scenario occurs when the request has a request body that is not valid.

   
   

7. Operation Name Error

   This error occurs when the operation name is not valid.

   
   

8. OAuth Plugin Unavailable

   This error scenario can occur only for the below mentioned use cases:

   • If the path specified for the OAuth Plugin is wrong.
   • If there is no read permission for the OAuth Plugin jar.
   • If an OAuth related request is received when the OAuth plugin is disabled.

Note

Along with the above mentioned scenarios, plan level and resource level scenarios are also a part of gateway level fault scenarios. These scenarios are common to both REST and SOAP.

The following are the list of Plan level scenarios for both SOAP and REST faults:

1. Subscription Term Expired

   This scenario occurs when a subscription key’s term date has already expired.

   
   

2. Black listed IP

   This scenario occurs when a request is received from a blacklisted IP.

   
   

3. White listed IP

   This scenario occurs when a request comes from the non-configured whitelisted IP.

   
   

4. Subscription Key Expired

   This scenario occurs when a subscription key that is already cancelled is used in the calls.

   
   

5. Resource Not In Plan

   This scenario occurs when a request is received for the below-mentioned use cases:

   1. When a wrong method is provided.
   2. When an invalid exposure base path is provided.
   3. When the operation name in the request body is invalid for the subscribed plan.
   4. When the service is not subscribed by a user and the user tries to hit the API service using another subscription key.
   
   

The following are the list of Resource level scenarios for both SOAP and REST faults:

1. Request Time Out

   This scenario occurs when the backend does not respond within the configured request timeout.

   
   

2. Invalid Authentication

   This scenario occurs when the authentication fails at gateway.

   For both Basic Authentication and WS Security type, as configured in the portal for security type under API Packs–>Usage Plans–>policies–>Security policy and the security type credentials under Subscription menu.

   1. Blank in username and valid in password
   2. Valid in Username and blank in password
   3. Blank in both Username and password
   4. Invalid in username and valid in password
   5. Valid in username and invalid in password
   6. Invalid in both username and password
   7. When authorization header is not present

   This scenario can also occur for OAuth based Authentication when the OAuth token provided is invalid.

   
   

3. Rate Limit Exceeded

   This scenario occurs when a request exceeds the rate limit as provided in the configured service.

   Example:

   1. Configure the rate limit (Example: 4) in rate limit type policy
   2. Associate the corresponding rate limit policy in plan
   3. Hit the gateway, once the rate limit exceeded (on 5th hit), the above scenario occurs.
   
   

4. Monthly Limit Exceeded

   This scenario occurs when a request exceeds the monthly usage limit as provided in the configured service.

   Examples:

   a. Configure the consumption limit (Example: number of requests as 5 in limits field) in Usage plan—>limits tab b. Hit the gateway, if the request exceeds the consumption limit (on 6th request hit), the above scenario occurs.

   
   

5. Endpoint Limit Exceeded

   This scenario occurs when a request causes the number of requests to exceed the rate limit as provided in the configured service in an endpoint level (Backend).

   Examples:

   1. Configure the endpoint protection limit (Example: 10) in backend endpoint for request count limit type
   2. Hit the gateway, if it exceeds the protection limit for the backend endpoint (say, on 11th hit), the above scenario occurs.
   
   

6. MCT Limit Exceeded

   This scenario occurs when the request load sent is more than the concurrent limit configured.

   Sample test scenarios:

   1. When same subscriber hits single operation
   2. When same subscriber hits multiple operations
   3. When different subscriber hits same single operation
   4. When different subscriber hits multiple operations
   
   

7. Request Handling Error

   This scenario occurs when some exception happens while processing the request.

   
   

8. Request Timeout:

   When the request is given and the response is not received within the specified time duration, as configured in timeout for that service, then the above scenario occurs, as configured in the portal under API—->Advanced—>Timeout.

   
   

9. Connection Closed :

   If the response is not received within the idle timeout mentioned in the gateway.properties file.

   
   

10. Connection Refused:

    This occurs for the below use cases:

    • When the backend is down.
    • When the backend point Protocol/ IP/ Port is invalid.

    
    

11. SSL Handshake Exception

    When the SSL connection is not established properly.

    
    

12. Response Handling Error

    This scenario occurs when there is any error during receiving and processing the response.

    
    

13. Unexpected Error in Endpoint Protection

    This scenario occurs when there is any unexpected error during enforcing Endpoint Protection.

    
    

14. Unexpected Error In Proxy

    This scenario occurs if an error occurs during MCT, Rate limit, Throttling, transformation policy enforcement.

    
    

15. Actual End point not Populated Error

    This scenario occurs when a request for the service that has dynamic routing configured, and the dynamic routing script in Mongo DB is null.

    
    

16. Request Schema Validation Failed

    This scenario occurs when a request fails schema validation for the request body.

    
    

17. Response Schema Validation Failed

    This scenario occurs when a response fails schema validation.

    
    

18. Invalid Configuration

    When the request is given for the service has dynamic routing configured, and the dynamic routing script contains the invalid configured backend endpoint name, then the above scenario occurs, as configured in the portal under API–>Endpoints–> Dynamic Routing.

    
    

19. Unexpected Error In Policy Validation

    This scenario occurs if some error occurs (rare case) during policy enforcement.

    
    

20. Connection Closed

    If the response is not received within the idle timeout mentioned in the gateway.properties file.

    
    

21. SSL connection failed

    This error scenario occurs when there is problem with SSL connection.

    
    

22. Connection Refused

    This occurs for the below use cases:

    • When the backend is down.
    • When the backend point Protocol/IP/Port is invalid.

Next Steps

In the next section, you will learn about how to export and import data.