3.5. Edit an API¶

In the last section, you created an API by giving it a name and type. The tasks in this section will allow you to control an API’s behavior. You will learn to add and edit API resources/operations, configure endpoints, handle Transformations and Schema Validation, and manage API Versions and their Visibility.

In this Section:

Add Descriptions to an API
Add API Resources
Edit API Resources
Delete Resources from an API
Schema Validations
Manage Transformations
Manage Data Recording
Configure Endpoints
Add Advanced Configurations
Add API Versions
Manage Visibility of an API
Edit an API Name
Send an API for Approval
Deprecate an API
Retire an API
Open an Approved or Published API for Editing
Discard Changes after opening an API for Editing
Search an API

Before you begin:

It is assumed that you have completed creating an API from the last section. If not, visit: Create an API.
Following UI screens are referenced in this section:
- APIs List screen
Fig. 3.64 APIs List screen
- API Configuration screen
Fig. 3.65 APIs Configuration screen
If not otherwise stated, the term “API” appearing in this section refers to “an API version.”
In the absence of any distinction made between SOAP and REST APIs, it must be assumed that the instructions given here apply to both cases.
The fields marked in asterisks are mandatory fields.

Common Tasks

Following are the common tasks identified in this section:

Navigating to the APIs List screen
To navigate to the APIs List screen:
- In the main navigation menu, click APIs.
Fig. 3.66 API menu

The APIs List screen displays.

Fig. 3.67 API screen
Navigating to the API Configuration screen
To navigate to the REST API Configuration screen:
1. Navigate to the APIs List screen.
2. In the APIs List screen, click the row that has the REST API you want to configure. The REST API Configuration screen displays.
Fig. 3.68 API Configuration screen

To navigate to the SOAP API Configuration screen:
1. Navigate to the APIs List screen.
2. In the APIs List screen, click the row that has the SOAP API you want to configure. The SOAP API Configuration screen displays.
Fig. 3.69 SOAP API Configuration screen

3.5.1. Add Descriptions to an API¶

Use Descriptions as a means to provide useful information about an API to your fellow portal users.

To add Descriptions to an API:

Navigate to the API Configuration screen.
In the API Configuration screen , click the Overview tab. The Overview tab screen displays.

Fig. 3.70 Overview tab screen
In the Short Description box, type a short description, if not already provided through the Add New API dialog box from the earlier task: Assign a Name and Type to an API.
In the Detailed Description box, type a detailed description.
In the Version Notes box, type version notes . Version Notes are used to specify what is new in the currently open version. By default, DigitMarket™ API Manager allots the first Version (1.0) to a newly created API version and populates the Version Notes box with the text: 1st Version.
Click Save As Draft to save changes and finish adding the Descriptions.

3.5.2. Add API Resources¶

3.5.2.1. Add Resources to a REST API¶

Resources can be added to a REST API using either of the following two methods:

Manual method
Upload method

Adding resources using the Manual method requires you to add resources by selecting a method, Resource name and Resource description. Conversely, if you add resources using the Upload method, you need to upload a Swagger Specifications file that contains the methods, Resource names and descriptions. The file is used to parse and load Resource definitions.

To add Resources to an API the Manual method:

Navigate to the REST API Configuration screen.
In the REST API Configuration screen, click the Resources tab.

Fig. 3.71 Resources tab screen

Scenario 1: The Resources tab displays the exposure base path and current list of resources (if the API already has a Resource added to it).

In the Exposure Base Path box, type an exposure base path for the new API.

The exposure base path is the root path that is visible to API consumers. It precedes the resource name and must be common to all resources. A URL with base path should resemble the following format: https://myorg-test.dmapim.com/v1/weather/forecast wherein https://myorg-test.dmapim.com/ is the URL fragment that stands for domain name of your company and /v1/weather is the base path of the exposed endpoint while /forecast is the Resource name. Here, you need to use the /v1/weather in the Exposure Basepath box.

Note

Rules to consider while adding/updating the exposure base path:

A minimum of three characters, including the initial special character (/)

Supports numerals (0 to 9), uppercase (A-Z), lowercase (a-z) and special characters (. - / _)

For the first two characters, begin with special character (/) followed by uppercase (A-Z), lowercase (a-z), numerals (0-9) and special characters (_ -)

From third character onwards, use numerals (0 to 9) or uppercase (A-Z) or lowercase (a-z) or special characters (/ _ - .) (can be 0 or multiple characters of those)

For characters third and above, use special character (.) and any of the numerals (0 to 9) or uppercase (A-Z) or lowercase (a-z) or special character (_) (can be 0 or multiple characters of those)

Must not end with (. or /)

Click Add New Resource to add a new resource to the API.

Fig. 3.72 New Resource

Note

The New Resource option is available only for APIs in Draft States.

The Add Resource dialog box displays.

Fig. 3.73 Add Resource dialog
In the Resource Name box, type the name of the Resource. The resource name should be prefixed with a forward slash, i.e., “/” as in “/forecast”

The Resource name represents a data entity. The name that you choose should be easily identifiable with the information it is intended to provide. Since RESTful is a state, naming a Resource as a noun as opposed to a verb is more beneficial as verbs are generally reserved for commands. For instance, in the URL: https://myorg-test.dmapim.com/v1/weather/forecast, /forecast is the Resource name and has a noun form. For an example of the verb form in a URL, let us take a look at our next URL example: https://myorg-test.dmapim.com/v1/weather/capture. Here /capture is a verb form.

Note

Resource name can be alphanumeric and must not more than 250 chars long.
Click the Method drop-down list to select the method to be used for the Resource. You find HTTP methods GET, PUT, POST, DELETE, and PATCH in the drop-down list.

Fig. 3.74 Add Resource
In the Description box, type a description for the Resource.
Click Add to save the added Resource. The Resource is added to the resource list. Use the search box to search for the required resources.

The Pagination feature at the bottom-right corner of the Resources tab allows you to choose the number of resources to display per page. Twenty entries per page is displayed by default, but you can customize it by entering your required value in the text box at the bottom-right corner of the page. Use the previous and next icons to navigate between the pages.
Click Save as Draft to save changes.

DigitMarket™ API Manager uses the now added resources to create a Swagger Specifications (YAML) file.

Scenario 2: When users add the exposure basepath first and then add the resources manually.

Exposure path is given as shown in the figure:

Fig. 3.75 Exposure Path
Click New Resource to display Add Resource page where Exposure Path will be auto-populated with the given exposure path shown in the above step.
User has to populate all the fields like Resource Name, Method and Description. Click Add to add the resource to the API or click Cancel to exit.

Fig. 3.76 Add Resource

Scenario 3: When users add resources manually without adding the exposure basepath.

Exposure path is not provided and click on Add New Resource as shown in the figure:

Fig. 3.77 Exposure Path
Click Add New Resource to display Add Resource page where user has to provide Exposure Path and other fields like Resource Name, Method and Description. Click Add to add the resource to the API or click Cancel to exit.

Fig. 3.78 Add Resouce

To add Resources using Upload method:

Navigate to the REST API Configuration screen.
In the REST API Configuration screen, click the Resources tab.

Fig. 3.79 Resource tab
In the Resources tab, click Upload a Swagger File to upload a YAML file or JSON file(s) with Swagger Specifications. When you select the required file from your computer and click Open, the Upload a Swagger file dialog appears.

Fig. 3.80 Upload a Swagger File
Click to select the check box Also overwrite manually created resources to remove resources, if any, from an earlier upload before adding resources from the newly uploaded YAML file. Initially, Also overwrite manually created resources is displayed as disabled. By selecting the checkbox, manually created resources will be overriden.
Click to select the Exposure Base Path from the radio button options: Use existing Exposure Base Path or Use Exposure Base Path from file. You can also edit the existing Exposure Base Path. Consider the rules mentioned earlier while updating the exposure base path.
Click Proceed. The chosen file displays alongside the Upload a Swagger file button. Multiple JSON files can also be uploaded in a zip file. For more information, refer the topic: Supporting Multiple JSON File Upload.
Click Save as Draft to save changes.

DigitMarket™ API Manager retrieves Resource information from the uploaded YAML file, and accordingly updates/overwrites the resources list. Use the search box to search for the required operations.

Note

You can add a new Resource to an API only if the API is in its Draft State.

Supporting Multiple JSON File Upload

You can also add resources for REST APIs from multiple JSON files. This can be done by compressing all the JSON files in a Zip file format and uploading the same on the application. Resource information from the zipped JSON file will then be extracted and retrieved. A JSON file consists of resources and schemas. A resource contains application data and information that is specific to Rest APIs. Schemas give information about what a resource looks like.

For a REST API, resource information can exist in multiple JSON files. To upload these files in bulk, they must be zipped. Each zipped file contains one master file and many child files. The master file will contain links to all the child files. When the zipped JSON file is uploaded, a node service performs the extraction process on the JSON file. The node service first reads the JSON file. It then identifies the master and child files. Once the master and child files are identified, it extracts the resource information from the individual JSON files and combines it into a single file that contains all the resources. The node service then sends this file to the application database.

3.5.2.2. Add Operations to a SOAP API¶

You can add Operations to a SOAP API using the WSDL Spec method whereby you need to upload a WSDL Specifications file.

The WSDL Specifications file contains all the information necessary to invoke methods of a SOAP web service. DigitMarket™ API Manager parses this file to load operations, which is then populated into the API Operations definition for SOAP APIs.

The file formats that are allowed to be imported are WSDL files and XSD files and Zip of WSDL and XSD files. An XSD file contains the schema for the WSDL file.

To learn more about WSDL files, refer the topic: API.

Note

All Operations that need to go into an API version through the WSDL file can only be added as a whole, not individually.

To add Operations to a SOAP API:

Navigate to the SOAP API Configuration screen.
In the SOAP API Configuration screen, click the Operations tab.

Fig. 3.81 Operations tab
In the Operations tab, click Upload a WSDL file to upload a WSDL file. Browse your computer to locate and open the WSDL/Zip file. When you select the required file from your computer and click Open, the Upload a WSDL file dialog appears.

Fig. 3.82 Upload a WSDL File
Click to select the Exposure Base Path from the radio button options: Use Exposure Base Path from file or Enter Base Path manually.

Note

Rules to consider while adding/updating the exposure base path:

A minimum of three characters, including the initial special character (/)

Supports numerals (0 to 9), uppercase (A-Z), lowercase (a-z) and special characters (. - / _)

For the first two characters, begin with special character (/) followed by uppercase (A-Z), lowercase (a-z), numerals (0-9) and special characters (_ -)

From third character onwards, use numerals (0 to 9) or uppercase (A-Z) or lowercase (a-z) or special characters (/ _ - .) (can be 0 or multiple characters of those)

For characters third and above, use special character (.) and any of the numerals (0 to 9) or uppercase (A-Z) or lowercase (a-z) or special character (_) (can be 0 or multiple characters of those)

Must not end with (. or /)

Click Proceed. The chosen file displays alongside the Upload a WSDL File button.
Click Save as Draft to save changes. You can find the imported information from the WSDL/Zip file populated under the Operation Name column in API Configuration screen. The Exposure Base Path is also automatically filled from the imported WSDL file. Use the search box to search for the required operations. The Pagination feature at the bottom-right corner of the Operations tab allows you to choose the number of operations to display per page. Twenty entries per page is displayed by default, but you can customize it by entering your required value in the text box at the bottom-right corner of the page. Use the previous and next icons to navigate between the pages.

Fig. 3.83 WSDL Operations

3.5.3. Edit API Resources¶

3.5.3.1. WSDL Re-upload¶

WSDL files are used to create and configure SOAP APIs. DigitMarket™ API Manager through its Gateway allows users to upload the WSDL files for adding operations to a SOAP API. You can read about how to add operations to a SOAP API, here: Add Operations to a SOAP API.

If there is an error in the uploaded WSDL file, or a new operation has to be added to / deleted from the API, the user will have to re-upload a new WSDL file in the same API. The WSDL re-upload feature allows users to re-upload a WSDL/Zip file in the same SOAP API. Users will be able to add/delete operations, as well as make changes to the existing operations within the same API.

To re-upload a WSDL file:

From the API menu, navigate to the SOAP API Configuration screen.
On the SOAP API Configuration screen, click the drop-down list and select Open For Edit option to edit the API in the Draft state.

Fig. 3.84 Open for Edit

Note

A SOAP API should be in draft state to re-upload a WSDL file. Only APIs in Published and Approved states can be converted into Draft for revision.

Once the API is opened for editing, you can upload/re-upload a WSDL file.
To re-upload a WSDL file, click the Operations tab. The Operations tab screen displays.

Fig. 3.85 Operations tab
In the Operations tab, click Upload a WSDL file to upload a new WSDL file. Previously uploaded WSDL file name will be displayed next to the Upload a WSDL file button. When you select the required file from your computer and click Open, the Upload a WSDL file dialog appears.

Fig. 3.86 Upload a WSDL File
Click to select the Exposure Base Path from the radio button options: Use existing Exposure Base Path or Use Exposure Base Path from file. You can also edit the Existing Exposure Base Path using the Edit icon .
Click Proceed.

Upon clicking the Proceed button, the Edit WSDL File dialog displays the following tabs:
- Unaltered Operations
- Missing Operations
- New Operations
- Map Operations
Unaltered Operations:

Unaltered Operations tab displays the list of operations that are present in the last approved/published WSDL file as well as the file you want to re-upload. The unchanged operations from the existing WSDL file is automatically populated under this tab.

Fig. 3.87 Unaltered Operations

Note

Comparison of the revised WSDL file is always made with the last approved/published WSDL file and not the last uploaded file.
- Click Next to navigate to the Missing Operations tab or Cancel to revert the changes.
Missing Operations:

Operations that are present in the last approved/published WSDL file but not in the file you want to re-upload are displayed under the Missing Operations tab. These operations are missing from the revised WSDL file because they may have been deleted or updated in the revised version.

Fig. 3.88 Missing Operations

Check-boxes are displayed alongside each missing operation. Click each checkbox to update the operation in the revised version, else they will be automatically deleted.

Note

If any of the operations in the existing WSDL file is associated with a pack (An API pack is a collection of resources/operations selected from Approved or Published APIs for use by consumers. For more information, refer: API Pack) then the existing WSDL file cannot be deleted. An error message is displayed in such case: Failed to delete operations, since operation is associated with pack(s).

Note

Operations associated with API Packs in the existing WSDL file, must also be present in the revised WSDL file for re-upload.
- Click Next to navigate to the New Operations tab.
New Operations:

New Operation tab lists the Operations that are present in the file you want to re-upload but not in the last approved/published WSDL file. These are the newly found operations in the revised WSDL file that have to be added to the API.

Fig. 3.89 New Operations

Check-boxes are displayed alongside each new operation. Click each check-box to update the operation in the revised version for one-to-one mapping.
- Click Next to navigate to the Map Operations tab.
Map Operations:

One-to-one mapping of Missing Operations to New Operations is done under Map Operations tab.

Fig. 3.90 Map Operations

Under New Operation Name column, click the drop-down list to select the operation names to be mapped.

Fig. 3.91 New Operation Name

Note

Ensure that you choose an equal number of missing and new operations to map.
After mapping the required operations, click Save. The Confirm Override window displays. The Confirm Override window gives a summary of the Mapped Operations, Operations to be added and Operations to be deleted. Click Confirm to confirm the WSDL file override or click Map Again to return to the Map Operations screen.

Fig. 3.92 Confirm override

If the save is successful, the following message displays.

Fig. 3.93 Success message

You can find the list of operations imported from the WSDL/Zip file populated into under the Operation Name column. If exposure base path from file is used, it gets auto-populated from the revised WSDL/Zip file. .

3.5.3.2. Swagger Re-upload¶

Swagger files are used to create and configure REST APIs. The Swagger re-upload feature allows users to re-upload a JSON/YAML file in the same REST API.

To re-upload a Swagger file:

From the API menu, navigate to the REST API Configuration screen.
On the REST API Configuration screen re-upload screen, click the drop-down list and select Open For Edit option to edit the API in the Draft state.

Fig. 3.94 Open for Edit

Note

A REST API should be in draft state to re-upload a JSON/YAML file. Only APIs in Published and Approved states can be converted into Draft for revision.

Once the API is opened for editing, you can upload/re-upload a JSON/YAML file.
To re-upload a Swagger file, click the Resource tab. The Resource tab screen displays.

Fig. 3.95 Resource tab
In the Resource tab, click Upload a Swagger file to upload a new JSON/YAML file. Previously uploaded JSON/YAML file name will be displayed next to the Upload a Swagger file button. When you select the required file from your computer and click Open, the Upload a Swagger file dialog appears.

Fig. 3.96 Upload a Swagger file
Click to select the Exposure Base Path from the radio button options: Use existing Exposure Base Path or Use Exposure Base Path from file. You can also edit the existing exposure base path using the Edit icon .
To rewrite all your existing resources with the resource from the file you upload, select the Also overwrite manually created resources check box.
Click Proceed.

Upon clicking Proceed button, the Edit Swagger File dialog displays the following tabs:
- Unaltered Resources
- Missing Resources
- New Resources
- Map Resources
Unaltered Resources:

Unaltered Resources tab displays the list of resources that are present in the last approved/published JSON/YAML file as well as the file you want to re-upload. The unchanged resources from the existing JSON/YAML file is automatically populated under this tab.

Fig. 3.97 Unaltered Resources

Note

Comparison of the revised JSON/YAML file is always made with the last approved/published JSON/YAML file and not the last uploaded file.
- Click Next to navigate to the Missing Resources tab or Cancel to revert the changes.
Missing Resources:

Resources that are present in the last approved/published JSON/YAML file but not in the file you want to re-upload are displayed under the Missing Resources tab. These resources are missing from the revised JSON/YAML file because they may have been deleted or updated in the revised version.

Fig. 3.98 Missing Resources

Check-boxes are displayed alongside each missing resources. Click each checkbox to update the resource in the revised version, else they will be automatically deleted.

Note

If any of the resource in the existing JSON/YAML file is associated with a pack (An API pack is a collection of resources/operations selected from Approved or Published APIs for use by consumers. For more information, refer: API Pack) then the existing JSON/YAML file cannot be deleted. An error message is displayed in such case: Failed to delete operations, since operation is associated with pack(s).

Note

Resources associated with API Packs in the existing JSON/YAML file, must also be present in the revised JSON/YAML file for re-upload.
- Click Next to navigate to the New Resources tab.
New Resources:

New Resources tab lists the Resources that are present in the file you want to re-upload but not in the last approved/published JSON/YAML file. These are the newly found resources in the revised JSON/YAML file that have to be added to the API.

Fig. 3.99 New Resources

Check-boxes are displayed alongside each new resource. Click each check-box to update the resource in the revised version for one-to-one mapping.
- Click Next to navigate to the Map Resources tab.
Map Resources:

One-to-one mapping of Missing Resource to New Resource is done under Map Resource tab.

Fig. 3.100 Map Resources

Click the drop-down list to select the resource names to be mapped.

Fig. 3.101 New Resources Name

Note

Ensure that you choose an equal number of missing and new resource to map.
After mapping the required resource, click Save. The Confirm Override window displays. The Confirm Override window gives a summary of the Mapped Resources, Resources to be added and Resources to be deleted. Click Confirm to confirm the JSON/YAML file override or click Map Again to return to the Map Resource screen.

Fig. 3.102 Confirm override

If the save is successful, the following message displays.

Fig. 3.103 Success message

You can find the list of resources imported from the JSON/YAML file populated into under the Resource Name column. If exposure base path from file is used, it gets auto-populated from the revised JSON/YAML file.

3.5.3.3. Edit a REST API Resource¶

To edit an API Resource:

Navigate to the REST API Configuration screen.
In the REST API Configuration screen, click the Resources tab. The current list of resources displays.

Fig. 3.104 Resource tab
Click the edit icon corresponding to the row that has the Resource you want to edit. The Edit Resource dialog box displays.

Fig. 3.105 Edit Resource dialog
Repeat steps 5, 6 and 7 from the earlier task: To add Resources to an API using Manual method.
Click Update to update the Resource.
Click Save as Draft to save changes made to the Resources tab.

Note

You can edit a Resource for an API Version that is in its Draft state.

Note

Upon any changes in the artifacts, the artifacts needs to be repropagated.

3.5.4. Delete Resources from an API¶

DigitMarket™ API Manager allows users to delete a Resource only if:

the API version to which it belongs is in its Draft state.
the Resource under that API version is not attached to any Usage Plan.

To delete a Resource from an API:

Navigate to the REST API Configuration screen.
In the API Configuration screen, click the Resources tab. The current list of resources displays.

Fig. 3.106 Resource list
Click the delete icon corresponding to the row that has the Resource you want to delete. The Resource is removed from the Resource list.
Click Save as Draft to save changes.

Note

Change the Exposure Base Path to match the format /v1/weather as discussed earlier.

Note

You can add Operations to an API only if the API is in its Draft State.

Note

Exposure Base path for two different versions of an API cannot be the same for both Production and Sandbox environment.

3.5.5. Schema Validations¶

DigitMarket™ API Manager allows the user to upload JSON and XSD schema documents against a REST API at Resource level. The Gateway then uses this JSON/XSD document to validate requests and responses based on the schema and content type in the document. Users can turn the schema validation feature on or off by enabling/disabling the schema validation for a Resource depending on their requirements.

To enable Schema Validation for a REST API:

Navigate to the REST API Configuration screen.
In the REST API Configuration screen, click the Schema Validation tab. The tab screen lists all the Resources added to the REST API.

Fig. 3.107 REST Schema Validation
Select the checkbox corresponding to the Resource that you wish to enable for Schema Validation. The Select All checkbox next to the Method header allows you to select all the resources. This enables the Upload File buttons in the JSON Schema and XSD Schema columns corresponding to the Resource.
In the JSON Schema column, corresponding to the selected Resource, click Upload File to select a JSON Schema file from your computer. The file must have a JSON extension (i.e., .json).
In the XSD Schema column, corresponding to the selected Resource, click Upload File to select a XSD Schema file in the XSD or ZIP format from your computer. The file must have either XSD extension (i.e., .xsd) or a ZIP extension (i.e., .zip).

Note

If no files are uploaded despite selecting the checkbox(es) corresponding to a Resource, the DigitMarket™ API Manager Gateway uses Swagger information from Swagger Specifications to complete the validation.
Click Save as Draft to save changes.

Note

JSON schema validation is used as a validation mechanism to ensure the JSON requests conform to the structure and requirements as present in the standard JSON document.

Note

XSD schema validation is used as a validation mechanism to ensure that the XML requests conform to the structure and requirements as present in the standard XML document.

Note

For SOAP APIs, request and response payloads are validated against the schema from the uploaded WSDL file.

3.5.6. Manage Transformations¶

In DigitMarket™ API Manager, Transformations allow users to carry out the following operations:

Make Content modification, injection and removal
Accept user-provided JavaScript for transforming REST and SOAP messages
Change message exchange protocol from REST to SOAP and vice-versa

For more information on Transformations, refer Transformations.

How it works?

A predefined primary object called customTransformation allows the user to define transformation methods used in DigitMarket™ API Manager. This object provides six pre-defined methods that can be implemented by the user to transform requests, responses and error objects. DigitMarket™ API Manager provides helper methods to write the code that will do the actual transformation through these six methods.

Following are the four Transformation methods used for REST Transformations :

Request Header
Request Body
Response Header
Response Body

Following are the two Transformation methods used for SOAP Transformations :

Request SOAP Header
Response SOAP Header

The above methods are assisted by helper methods that perform the actual transformation operation. Refer the sample REST and SOAP Transformation scripts in the topics below to gain more understanding about helper methods.

To learn more about Transformations, refer: Transformations.

3.5.6.1. REST JSON Transformation¶

Following are the Transformation methods used in JSON Transformation for REST APIs:

Table 3.3 JSON Transformation Methods¶

Methods Description

transformRequestHeader() Use this method to transform HTTP Request Header

transformRequestBody()
Use this method to transform Request Body. You can transform Request Body for the following:

Modify existing key or existing value or both

Add a new JSON element

Remove a JSON element

transformResponseHeader() Use this method to transform HTTP Response Header

transformResponseBody()
Use this method to transform Response Body. You can transform Response Body for the following:

Modify existing key or existing value or both

Add a new JSON element

Remove a JSON element

Following are the Helper Transformation Methods used in JSON Transformation for REST APIs:

Table 3.4 JSON Transformation Helper Methods¶

Methods Method Description Parameters Parameter Description

addRequestHeader(key, value) Use this method to add header to Request Key

Value

modifyJsonElement(jsonBody, jsonPath, keyToModify, replaceKey, replaceValue) Use this method to modify JSON element (i.e., existing key or value or both) jsonBody JSON body can be obtained using customTransformation.getJsonBody()

jsonPath the path should indicate the parent key of the key to be modified

keyToModify indicates the key whose key or value should be modified

replaceKey indicates the new key to be replaced

replaceValue indicates the new value to be replaced

modifyJsonElement(jsonBody, jsonPath, keyToModify, replaceKey, replaceValue, index) Use this method to modify JSON element (i.e., existing key or value or both) within a JSON array jsonBody JSON body can be obtained using customTransformation.getJsonBody()

jsonPath the path should indicate the parent key of the key to be modified

keyToModify indicates the key whose key or value should be modified

replaceKey indicates the new key to be replaced

replaceValue indicates the new value to be replaced

index JSON array index

addJsonElement(jsonBody, jsonPath, parentKey, addKey, addValue) Use this method to add new JSON element to JSON Body (i.e., new key and value pair) jsonBody JSON body can be obtained using customTransformation.getJsonBody()

jsonPath the path should indicate the key under which new key value pair has to be added

parentKey indicates the key for which new value key pair has to be added

addKey indicates the new key to add

addValue indicates the new value to add

addJsonElement(jsonBody, jsonPath, parentKey, addKey, addValue, index) Use this method to add new JSON element to JSON Body (i.e., new key and value pair) jsonBody JSON body can be obtained using customTransformation.getJsonBody()

jsonPath the path should indicate the key under which new key value pair has to be added

parentKey indicates the key for which new value key pair has to be added

addKey indicates the new key to add

addValue indicates the new value to add

index JSON array index

removeJsonElement(jsonBody, jsonPath, keyToRemove) Use this method to remove JSON element jsonBody JSON body can be obtained using customTransformation.getJsonBody()

jsonPath the path should indicate the parent key of the key that should be removed

keyToRemove key that needs to be removed from JSON Body

removeJsonElement(jsonBody, jsonPath, keyToRemove, index) Use this method to remove JSON element from within a JSON array jsonBody JSON body can be obtained using customTransformation.getJsonBody()

jsonPath the path should indicate the parent key of the key that should be removed

keyToRemove key that needs to be removed from JSON Body

index JSON array index

addResponseHeader(key, value) Use this method to add header to Response Key

Value

getRequestHeaderEntries() This method gets all HTTP headers present in the HTTP request headers during transformation. Nil No parameters required

getRequestHeaderEntries().toString().match(‘<header name>’) This method returns the header name if the header exists and returns null if it doesn’t exist. Header name Header name parameter

Sample JSON Transformation Script

To add Request Header:

var obj = new Object();
obj.transformRequestHeader = function(customTransformation){
customTransformation.addRequestHeader("CustomTransform","Checking the transformation");
return customTransformation;
}

To modify/add/remove JSON element from Request Body:

obj.transformRequestBody = function(customTransformation){
 var jsonBody = customTransformation.getJsonBody();
 var jsonPath = "$";
 var keyToModify = "Parameters";
 var replaceKey = "GlobalParameters";
 var replaceValue = "";
  if(jsonBody != "" && jsonPath != "" && keyToModify != ""){
   customTransformation.modifyJsonElement(jsonBody, jsonPath,keyToModify, replaceKey, replaceValue);
   }

 var jsonBody = customTransformation.getJsonBody();
 var jsonPath = "$..GlobalParameters";
 var parentKey = "GlobalParameters";
 var addKey = "parameterName";
 var addValue = "parameterActualValue";
  if(jsonBody != "" && jsonPath != "" && parentKey != "" && addKey != "" && addValue != ""){
   customTransformation.addJsonElement(jsonBody,jsonPath,parentKey,addKey,addValue);
  }

 var jsonBody = customTransformation.getJsonBody();
 var jsonPath = "$..GlobalParameters";
 var keyToRemove = "opResultPrecision";
  if(jsonBody != "" && jsonPath != "" && keyToRemove != ""){
    customTransformation.removeJsonElement(jsonBody,jsonPath,keyToRemove");
  }
return customTransformation;
}

To add Response Header:

obj.transformResponseHeader = function(customTransformation){
   customTransformation.addResponseHeader("Resource","Unknown");
         return customTransformation;
   }

To modify/add/remove JSON element from Response Body:

obj.transformResponseBody = function(customTransformation){
 var jsonBody = customTransformation.getJsonBody();
 var jsonPath = "";
 var keyToModify = "";
 var replaceKey = "";
 var replaceValue = "";
 if(jsonBody != "" && jsonPath != "" && keyToModify != ""){
   customTransformation.modifyJsonElement(jsonBody, jsonPath,keyToModify, replaceKey, replaceValue);
 }

 var jsonBody = customTransformation.getJsonBody();
 var jsonPath = "";
 var parentKey = "";
 var addKey = "";
 var addValue = "";
 if(jsonBody != "" && jsonPath != "" && parentKey != "" && addKey != "" && addValue != ""){
   customTransformation.addJsonElement(jsonBody,jsonPath,parentKey,addKey,addValue);
 }

 var jsonBody = customTransformation.getJsonBody();
 var jsonPath = "";
 var keyToRemove = "";
 if(jsonBody != "" && jsonPath != "" && keyToRemove != ""){
   customTransformation.removeJsonElement(jsonBody,jsonPath,keyToRemove");
 }

 return customTransformation;
}
)

To delete request header :

obj.transformRequestHeader = function(customTransformation){
customTransformation.deleteReqHeader("Content-Type");
return customTransformation;
}

To delete response header

obj.transformResponseHeader = function(customTransformation){
customTransformation.deleteResponseHeader("Content-Type");
return customTransformation;
}

3.5.6.2. REST XML Transformation¶

Following are the main Transformation Methods used in XML Transformation for REST APIs:

Table 3.5 XML Transformation Methods¶

Methods Method Description

transformRequestHeader() Use this method to transform HTTP Request Header

transformRequestBody()
Use this method to transform XML Request Body. You can transform Request Body for the following:

Modify existing XML node name or node value or both

Add a new XML element

Remove an XML element

transformResponseHeader() Use this method to transform HTTP Response Header

transformResponseBody()
Use this method to transform XML Response Body. You can transform Response Body for the following:

Modify existing XML node name or node value or both

Add a new XML element

Remove an XML element

Following are the Helper Methods used in XML Transformation for REST APIs:

Table 3.6 XML Transformation Helper Methods¶

Methods Method Description Parameters Parameter Description

addRequestHeader(key, value) Use this method to add header to Request Key

Value

modifyXmlElement(xmlBody, xPath, NodeToReplace, replaceNodeName, replaceNodeValue) Use this method to modify XML element (i.e. existing node name or node value or both) xmlBody XML body obtained from the code using customTransformation.getXmlBody()

xPath the path should indicate the XML node to be modified

NodeToReplace indicates the node whose node name or node value should be modified

replaceNodeName indicates the new node name to be replaced with

replaceNodeValue indicates the new node value to be replaced with

addXmlElement(xmlBody, parentNode, addNode, addNodeValue) Use this method to add new XML element to XML Body (i.e., new node ) xmlBody XML body obtained from the code using customTransformation.getXmlBody()

parentNode indicates the node under which new node has to be added

addNode indicates the new node name to add

addNodeValue indicates the new node value to add

removeXmlElement(xmlBody,removeNode) Use this method to remove XML element xmlBody XML body obtained from the code using customTransformation.getXmlBody()

removeNode Name of the node that should be removed

addResponseHeader(key, value) Use this method to add header to Response Key

Value

getRequestHeaderEntries() This method gets all HTTP headers present in the HTTP request headers during transformation Nil No Parameters Required

getRequestHeaderEntries().toString().match(<header name>) This method returns the header name if the header exists and returns null if it doesn’t exist. Header Name Header Name Parameter

Sample XML Transformation Scripts

To add Request Header:

obj.transformRequestHeader = function(customTransformation){
customTransformation.addRequestHeader("CustomTransform","Checking the transformation");
return customTransformation;
}

To modify/add/remove XML element from Request Body:

obj.transformRequestBody = function(customTransformation){

 var xmlBody = customTransformation.getXmlBody();
 var xPath = "//FIRSTNAME";
 var NodeToReplace = "FIRSTNAME";
 var replaceNodeName = "F_NAME";
 var replaceNodeValue = "KUSUM";
 if(xmlBody != "" && xPath != "" && NodeToReplace != ""){
  customTransformation.modifyXmlElement(xmlBody, xPath,NodeToReplace, replaceNodeName, replaceNodeValue);
  }

 var xmlBody = customTransformation.getXmlBody();
 var parentNode = "CUSTOMER";
 var addNode = "parameterName";
 var addNodeValue = "parameterActualValue";
 if(xmlBody != "" && parentNode != "" && addNode != "" && addNodeValue != ""){
   customTransformation.addXmlElement(xmlBody, parentNode, addNode, addNodeValue);
  }

 var xmlBody = customTransformation.getXmlBody();
 var removeNode = "CITY";
 if(xmlBody != "" && removeNode != ""){
   customTransformation.removeXmlElement(xmlBody,removeNode);
  }

return customTransformation;
}

To add Response Header:

obj.transformResponseHeader = function(customTransformation){
 customTransformation.addResponseHeader("Resource","Unknown");
 return customTransformation;
}

To modify/add/remove XML element from Response Body:

obj.transformResponseBody = function(customTransformation){

 var xmlBody = customTransformation.getXmlBody();
 var xPath = "";
 var NodeToReplace = "";
 var replaceNodeName = "";
 var replaceNodeValue = "";
 if(xmlBody != "" && xPath != "" && NodeToReplace != ""){
    customTransformation.modifyXmlElement(xmlBody, xPath,NodeToReplace, replaceNodeName, replaceNodeValue);
 }

 var xmlBody = customTransformation.getXmlBody();
 var parentNode = "";
 var addNode = "";
 var addNodeValue = "";
 if(xmlBody != "" && parentNode != "" && addNode != "" && addNodeValue != ""){
   customTransformation.addXmlElement(xmlBody, parentNode, addNode, addNodeValue);
 }

 var xmlBody = customTransformation.getXmlBody();
 var removeNode = "";
 if(xmlBody != "" && removeNode != ""){
      customTransformation.removeXmlElement(xmlBody,removeNode);
 }

return customTransformation;

3.5.6.3. SOAP Transformation¶

Following are the main Transformation methods used in SOAP Transformation:

Table 3.7 SOAP Transformation Methods¶

Methods Description

transformRequestHeader() Use this method to transform HTTP request header

transformSoapRequestHeader() Use this method to transform SOAP header in request payload

transformSoapResponseHeader() Use this method to transform SOAP header in response payload

transformRequestBody() Use this method to transform SOAP body in request payload

transformResponseHeader() Use this method to transform HTTP response header

transformResponseBody() Use this method to transform SOAP body in response payload

transformRequestSoapfault() Use this method to transform gateway fault messages

Following are the Helper methods used in Transformation of SOAP APIs:

Table 3.8 SOAP Helper Transformation Methods¶

Methods Method Description Parameters Parameter Description

addElementToExistingSoapHeader(namespace, namespaceURI, localPart, text) Use this method to add SOAP header elements to existing SOAP header namespace Namespace prefix to be added along with the node name

namespaceURI NameSpace URI for the prefix

localPart indicates the node name

text indicates the text to be created for the node

removeAttributeFromSoapHeader(namespace, element, attribute) Use this method to remove attribute from SOAP header namespace Namespace of the element

element Indicates the node name whose attribute should be removed

attribute indicates the name of the attribute to be removed

removeElementFromExistingSoapHeader(namespace, element) Use this method to remove SOAP header elements from existing SOAP header namespace Namespace of the element

element Indicates the node name that should be removed

addToHeaderFaultStructure(namespace, namespaceURI, localPart, text) Use this method to add header element to fault structure namespace Namespace prefix to be added along with the node name

namespaceURI NameSpace URI for the prefix

localPart indicates the node name

text indicates the text to be created for the node

addToDetailFaultStructure(namespace, namespaceURI, localPart, text) Use this method to add detailelement to fault structure namespace Namespace prefix to be added along with the node name

namespaceURI NameSpace URI for the prefix

localPart indicates the node name

text indicates the text to be created for the node

addNameSpaceToSoapEnvelope (customTransformation.getSMessage(), namespaceURI, prefix) Use this method to add XML namespace URI to the SOAP envelope customTransformation.getSMessage() This function returns the SOAP envelope

namespaceURI Namespace URI for the XML

prefix The prefix to be added to the Namespace URI

addNameSpacePrefixToNode (customTransformation.getSMessage(), namespacePrefix,nodeName,flag) Use this method to add Namespace prefix to the specified node customTransformation.getSMessage() This function returns the SOAP envelope

namespacePrefix Namespace prefix to be added to the node

nodeName Name of the node for which the prefix has to be added

flag The flag value can either be true or false. If it is true, the namespace prefix will be added to the specific node and all its child nodes. If it is false, the namespace prefix will be added only for that node.

Note

Below methods from the above list are also used in Data Recording:

addElementToExistingSoapHeader(namespace, namespaceURI, localPart, text)

removeAttributeFromSoapHeader(namespace, element, attribute)

removeElementFromExistingSoapHeader(namespace, element)

SOAP Sample Transformation Scripts

Transform SOAP Request Header:

obj.transformSoapRequestHeader = function(customTransformation){

  var corNamespace = "cor";
  var corNamespaceURI = "";

  customTransformation.addElementToExistingSoapHeader(corNamespace, corNamespaceURI, "SOATransactionID", customTransformation.getRequestId());
  customTransformation.addElementToExistingSoapHeader(corNamespace, corNamespaceURI, "applicationID", customTransformation.getCNane());
  customTransformation.addElementToExistingSoapHeader(corNamespace, corNamespaceURI, "providerID", customTransformation.getOrganization());
  customTransformation.addElementToExistingSoapHeader(corNamespace, corNamespaceURI, "originatorIP", customTransformation.getOriginatorIP());

          customTransformation.removeAttributeFromSoapHeader("wsse","Security","soapenv:mustUnderstand");
          customTransformation.removeAttributeFromSoapHeader("wsse","Security","mustUnderstand");


  customTransformation.finalizeTransformation();
  return customTransformation;
}

Transform SOAP Response Header:

obj.transformSoapResponseHeader = function(customTransformation){
 if(customTransformation.getSoapHeader()){
  customTransformation.removeElementFromExistingSoapHeader("cor", "applicationID");
      customTransformation.removeElementFromExistingSoapHeader("cor", "providerID");
      customTransformation.removeElementFromExistingSoapHeader("cor", "originatorIP");
      customTransformation.removeElementFromExistingSoapHeader("cor", "debugFlag");
      customTransformation.finalizeTransformation();
  }
return customTransformation;
}

Transform SOAP fault structure:

obj.transformRequestSoapfault = function(customTransformation){
 var corNamespace = "cor";
 var corNamespaceURI = "";

 customTransformation.addToHeaderFaultStructure(corNamespace, corNamespaceURI, "SOATransactionID", customTransformation.getRequestId());

 customTransformation.addToDetailFaultStructure(corNamespace, corNamespaceURI, "SOATransactionID", customTransformation.getRequestId());

 customTransformation.addToHeaderFaultStructure(corNamespace, corNamespaceURI, "SOAConsumerTransactionID");
return customTransformation;
}

3.5.6.4. Protocol Conversion¶

Helper methods used for Transformation in protocol conversion are as given below:

JSON to SOAP Conversion

To convert a JSON body to SOAP message, use the following method:

jsonToSoap(JsonObject jsonbody, String soapProtocol, String soapAction)

Table 3.9 Parameter Details¶
Parameter	Description
jsonbody	This can be obtained using customTransformation.getJsonBody()
SoapProtocol	This can be obtained using customTransformation.getJsonBody()
soapAction	This can be obtained using customTransformation.getJsonBody()

To get the incoming JSON request body, use the following code:

var jsonBody = customTransformation.getJsonBody();

To set the SOAP protocol, use the following code:

Note

SOAP protocol can either be SOAP_PROTOCOL_1_1 or SOAP_PROTOCOL_1_2.
Based on your requirements, you can change the SOAP protocol.

var soapProtocol = "SOAP_PROTOCOL_1_1";

To pass the soapAction attribute, use the following code. You can pass the attribute as an empty string in case it is unavailable.

var soapAction = "";

To convert JSON to SOAP, use the following code:

customTransformation.jsonToSoap(jsonBody, soapProtocol, soapAction);

Transformation script:

var obj = new Object();
obj.transformRequestHeader = function(customTransformation){
   customTransformation.addRequestHeader("CustomTransform","Checking the transformation");
   return customTransformation;
}

obj.transformRequestBody = function(customTransformation){
   var transformedReqBody;
   var jsonBody = customTransformation.getJsonBody();
   var soapProtocol = "SOAP_PROTOCOL_1_1";
   var soapAction = "http://webservice.ws.jax.learn.com/";
   if(jsonBody != "" && soapProtocol != ""){
     transformedReqBody = customTransformation.jsonToSoap(jsonBody, soapProtocol, soapAction);
   }

customTransformation.addNamespaceToXml(customTransformation.getSMessage(),"RESULT_STATUS","http://www.<example.com>/NetworkProvisioningService/Request.xsd","bsse");        customTransformation.addNamespaceToXml(customTransformation.getSMessage(),"BSOID","http://<example>.ie/coredata_1_0","cor");
  return customTransformation;
}

obj.transformResponseHeader = function(customTransformation){
   customTransformation.addResponseHeader("Resource","Header");
   return customTransformation;
}

obj.transformResponseBody = function(customTransformation){
   var jsonResponse;
   var soapMessage = customTransformation.getSMessage();
   if(soapMessage != ""){
     jsonResponse = customTransformation.soapToJson(soapMessage);
   }
   return customTransformation;
}

soapToJson(String soapMessage)

This method is used to convert SOAP messages to JSON.

Table 3.10 Parameters¶

Parameter Description

soapMessage This can be obtained using customTransformation.getSMessage()

Transformation script:

var obj = new Object();
obj.transformRequestHeader = function(customTransformation){
   customTransformation.addRequestHeader("CustomTransform","Checking the transformation");
   return customTransformation;
}
obj.transformRequestBody = function(customTransformation){
var soapMessage = customTransformation.getSMessage();
if(soapMessage != ""){
   customTransformation.soapToJson(soapMessage);
}
return customTransformation;
}
obj.transformResponseHeader = function(customTransformation){
customTransformation.addResponseHeader("Resource","Header");
return customTransformation;
}
obj.transformResponseBody = function(customTransformation){
   var soapResponse;
   var jsonBody = customTransformation.getJsonBody();
   var soapProtocol = "SOAP_PROTOCOL_1_1";
   var soapAction = null;
   if(jsonBody != "" && soapProtocol != ""){
     soapResponse = customTransformation.jsonToSoap(jsonBody, soapProtocol, soapAction);
   }
   return customTransformation;
}

xmlToSoap(String xml, String soapProtocol, String soapAction)

This method is used to convert an XML to SOAP message.

Table 3.11 Parameters¶

Parameter Description

xml This can be obtained by using customTransformation.getXmlBody()

soapProtocol

soapAction

Transformation script:

var obj = new Object();
obj.transformRequestHeader = function(customTransformation){
   customTransformation.addRequestHeader("CustomTransform","Checking the transformation");
   return customTransformation;
}

obj.transformRequestBody = function(customTransformation){
   var transformedReqBody;
   var xmlBody = customTransformation.getXmlBody();
   var soapProtocol = "SOAP_PROTOCOL_1_1";
   var soapAction = "http://webservice.ws.jax.learn.com/";
   if(xmlBody != "" && soapProtocol != ""){
      transformedReqBody = customTransformation.xmlToSoap(xmlBody, soapProtocol, soapAction);
   }
customTransformation.addNamespaceToXml(customTransformation.getSMessage(),"RESULT_STATUS","http://www.<example.com>/NetworkProvisioningService/Request.xsd\","bsse");
customTransformation.addNamespaceToXml(customTransformation.getSMessage(),"BSOID","http://<example>.o2.ie/coredata_1_0","cor");
return customTransformation;
}

obj.transformResponseHeader = function(customTransformation){
   customTransformation.addResponseHeader("Resource","Header");
   return customTransformation;
}

obj.transformResponseBody = function(customTransformation){
   var xmlResponse;
   var soapMessage = customTransformation.getSMessage();
   if(soapMessage != ""){
     xmlResponse = customTransformation.soapToXml(soapMessage);
   }
   return customTransformation;
}

soapToXml(String soapMessage)

This method can be used to convert a SOAP message to XML.

Table 3.12 Parameters¶

Parameter Description

soapMessage This can be obtained using customTransformation.getSMessage()

Transformation script:

var obj = new Object();
obj.transformRequestHeader = function(customTransformation){
   customTransformation.addRequestHeader("CustomTransform","Checking the transformation");
return customTransformation;
}
obj.transformRequestBody = function(customTransformation){
   var soapMessage = customTransformation.getSMessage();
   if(soapMessage  != ""){
     customTransformation.soapToXml(soapMessage);
   }
return customTransformation;
}
obj.transformResponseHeader = function(customTransformation){
   customTransformation.addResponseHeader("Resource","Header");
return customTransformation;
}
obj.transformResponseBody = function(customTransformation){
   var soapResponse;
   var xmlBody = customTransformation.getXmlBody();
   var soapProtocol = "SOAP_PROTOCOL_1_1";
   var soapAction = null;
   if(xmlBody != "" && soapProtocol != ""){
      soapResponse = customTransformation.xmlToSoap(jsonBody, soapProtocol, soapAction);
   }
return customTransformation;
}

addNamespaceToXml(String xml, String nodeName, String namespaceURI, String prefix)

This method can be used to add Namespace URI and prefixes to XML body.

Table 3.13 Parameters¶

Parameter Description

xml This can be obtained by using customTransformation.getXmlBody()

nodeName Name of the node for which prefix should be added

namespaceURI Namespace URI

prefix prefix to append to the node

To include Transformation at the Resource/Operation level:

Navigate to the REST/SOAP API Configuration screen.
In the REST/SOAP API Configuration screen, click the Transformations tab.

Fig. 3.108 REST Transformations tab

Fig. 3.109 SOAP Transformations tab

In the active sub-tab Resource Level/Operation Level, a list of all resources/operations that have been added to the API Version displays.
Under Enable, against the row that has the Resource/Operation for which you want to apply Transformations, click to select the check box.

Fig. 3.110 REST Resource for Transformation

Fig. 3.111 SOAP Operation for Transformation
Under Script, for the selected row, click the triple-dot button to display the Resource - Transformation Script dialog box.

Fig. 3.112 Transformation script button

Fig. 3.113 Transformation script dialog

Fig. 3.114 SOAP Transformation script dialog
In the Transformation Script box, type the JavaScript to be used for Transformation. The JavaScript provided here will be used by the Gateway to transform message payloads, response headers and body elements.
Click Submit to finish adding the Transformation details and close the current dialog box.
Click Save as Draft to save changes.

To include a Transformation at the API level:

Navigate to the API Configuration screen.
In the REST/SOAP API Configuration screen, click the Transformations tab.

Fig. 3.115 Transformation tab
Click the sub-tab API Level to display the API level sub-tab screen.

Fig. 3.116 API level sub-tab

Fig. 3.117 API level sub-tab
In the Transformation Script box, type the JavaScript that will be used for the transformation.
Click Save as Draft to save changes.

Note

Any Transformation done at API level applies to the API as a whole and takes precedence over the Resource/Operation level transformation at runtime. In cases where both levels of Transformations are included, API-level transformation is performed first and if the Resource/Operation-level Transformation is applicable for the Resource/Operation, then the Resource/Operation-level Transformation is applied to the message.

Note

You can add Transformations to an API only if the API is in its Draft State.

3.5.6.5. Payload Conversion¶

Payload is the actual message or body data that is transmitted in a request/response. DigitMarket™ API Manager through its Gateway allows users to perform payload conversion for REST services. Payload conversion is applicable for the following scenarios:

To convert incoming REST XML request payload to JSON payload and incoming JSON response to XML.
To convert incoming JSON request payload to RESTXML payload and incoming XML response to JSON.

In cases where the requesting and receiving applications are configured with different services, conversion is done by the Gateway so that the payload request/response is sent in the preferred data format to the appropriate application.

XML to JSON

Let us suppose that the client application supports XML service and the receiving application backend is configured with JSON service. In such cases for XML requests from the client, the Gateway will convert the request into JSON and send it to the backend. As the backend supports JSON, the response sent by it will be in JSON format. This response is converted to XML by Gateway and sent to the client application. Conclusion is that, conversion has taken place within the Gateway from XML to JSON for requests and vice versa for responses.

JSON to XML

Let us suppose that the client application supports JSON service and the receiving application backend is configured with XML service. In such cases for JSON requests from the client, the Gateway will convert the request into XML and send it to the backend. As the backend supports XML, the response sent by it will be in XML format. This response is converted to JSON by Gateway and sent to the client application. Conclusion is that, conversion has taken place within the Gateway from JSON to XML for requests and vice versa for responses.

None

Let us suppose that the client application backend is configured with JSON service and the receiving application also supports JSON. In such cases for JSON requests from client, the backend will send a JSON response. Conclusion is that, no conversion takes place, as the value None is rendered in this case.

Note

Although payload conversion does not take place, transformation will be applicable as per the transformation script.

To enable Payload Conversion for a REST API:

Navigate to the REST API Configuration page.
In the REST API Configuration screen, click the Transformations tab. The tab screen lists all the Resources added to the REST API. In the active sub-tab Resource Level, a list of all resources that have been added to the API Version displays.

Fig. 3.118 Resource Level
Under Payload Converter, against the row that has the Resource for which you want to apply payload conversion, click to select the drop-down list.

Fig. 3.119 Payload Converter

From the Payload Conversion drop-down list, select the required conversion scenario: None, XMLtoJSON and JSONtoXML.

Click Save as Draft to save changes.

Additionally, user can also upload a transformation JavaScript to the API to make content modification, addition and removal to the request and response elements and headers. For payload conversion, user can also modify the Content Type header in the transformation script. If not specified, the default Content Type value that is hardcoded in the Gateway will be used. In such cases payload conversion will take place first, and custom transformation will be applied on the converted payload.

For more information on transformation, refer Manage Transformations and to know how to upload a Transformation script, refer the topic ‘To include Transformation at the Resource/Operation level’ in that section .

Content-Type header

Let us suppose that both the client application and the receiving application backend is configured with different services, and payload conversion is required to send appropriate data. In a typical scenario, the payload conversion will take place first followed by the Content Type conversion. That is, the Content Type conversion will take place on the converted payload.

The Content Type header will be specified in the Transformation script. After payload conversion, the Gateway will modify the Content Type header of the converted payload by using the client specified value or default value (application/xml for XML payload and application/json for JSON payload) hardcoded in the Gateway and send it to the backend.

This payload and Content Type conversion is applicable for both request and response scenarios. In case of response, the Content Type will be defined by the backend, and conversion will take place in the Gateway.

The client may also modify the Content Type with custom value in the transformation script. If the Content-Type header is not modified in the script, or in case of faulty script, gateway will modify the headers, based on the converted payload, by using the default values (application/xml for XML and application/json) for JSON payload.

Accept header

If a request contains an Accept header, then the payload conversion for the request will occur based on the selected payload conversion value in the user interface value. Response transformation will be based on the Accept header and will be applicable to the scenarios discussed below.

XML to JSON

Let us suppose that the client application supports XML service and the receiving application backend is configured with JSON service. In such cases, for XML requests from the client, the Gateway will convert the request into JSON and send it to the backend. As the backend supports JSON, the response sent by it will be in JSON format. This response is converted to XML by Gateway based on the payload conversion value selected in the user interface. This is a typical payload conversion scenario.

If the client has specified the Accept header as JSON (application/json), then no payload conversion will take place as the response from the backend is already in JSON. Since the Accept header has been specified, this JSON response from the backend will be sent to the client application without payload conversion. If no Accept header is specified, payload conversion will take place, and JSON response from Gateway will be converted into XML for the client.

JSON to XML

Let us suppose that the client application supports JSON service and the receiving application backend is configured with XML service. If the client has specified the Accept header as XML (application/xml), then no payload conversion will take place as the response from the backend is already in XML. Since the Accept header has been specified, this XML response from the backend will be sent to the client application without payload conversion. If no Accept header is specified, payload conversion will take place, and XML response from Gateway will be converted into JSON for the client.

Note

If the Accept header is a value other than [application/xml or application/json or text/xml] then “Request Handling Error“ will be thrown by the Gateway.

GET requests do not have a request body. In cases where the incoming request is a GET request with an empty request body, the payload conversion will happen only for the response body.

For example, for an incoming GET request, if the payload conversion is selected as JSON to XML in the user interface, it is by default understood that the client application has JSON service configured while the backend supports XML service. In such case, the response coming from the backend will be in XML. The Gateway will perform payload conversion on the XML response and convert it to JSON to be sent to the client.

3.5.7. Manage Data Recording¶

DigitMarket™ API Manager allows the user to add a script based on a template that will be used to output data to be logged for each Resource/Operation. The script can be used to add, remove or modify (including masking elements to conceal certain data) from the requests and responses (including payloads and header information).

Refer Data Recording for more information.

Refer the table at the end of this topic to learn more about the methods used in Data Recording.

To add a data recording script to a Resource/Operation:

Navigate to the REST/SOAP API Configuration screen.
In the REST/SOAP API Configuration screen, click the Data Recording tab.

Fig. 3.120 REST Data Recording tab

Fig. 3.121 SOAP Data Recording tab

A list of Resource(s)/Operation(s) added to the API displays.
Under Script, against the resource/operation for which you wish to add a script, click the three-dot button to display the Resource level - Data Recording script/ Operation level - Data Recording Script dialog.

Fig. 3.122 REST Data Recording script dialog

Fig. 3.123 SOAP Data Recording script dialog
Click Submit to complete adding the script and return to the API Configuration screen.

Data Recording Methods

Following are the masking methods used in Data Recording:

Table 3.14 Data Recording - Masking Methods¶

Methods Description

maskJsonRequestBody() Use this method to mask JSON request body

maskJsonResponseBody() Use this method to mask JSON response body

maskRestXmlRequestBody() Use this method to mask REST XML request body

maskRestXmlResponseBody() Use this method to mask REST XML response body

maskRequestBody() Use this method to mask SOAP request body

maskResponseBody() Use this method to mask SOAP response body

Helper Methods Used

modifyElementUsingJsonPath(jsonBody, jsonPath, replaceText)

This method is used to mask JSON body.

Table 3.15 Helper Methods Used - modifyElementUsingJsonPath(jsonBody, jsonPath, replaceText)¶

Parameter Description

jsonBody Json Body can be obtained from the code

jsonPath JsonPath, the path should indicate the key whose value should be masked

replaceText The replace value used to mask

partialMaskingUsingJsonPath(jsonBody, jsonPath, startLen, endLen, maskUnmask)

This method is used to mask the JSON data partially.

Table 3.16 Helper Methods Used - partialMaskingUsingJsonPath(jsonBody, jsonPath, startLen, endLen, maskUnmask)¶

Parameter Description

jsonBody Json Body can be obtained from the code using transactionRecording.getXmlBody()

jsonPath JsonPath, the path should indicate the key whose value should be masked

startLen No. of starting characters in the jsonPath value to be masked/unmasked

endLen No. of last characters in the jsonPath value to be masked/unmasked

maskUnmask Indicates whether to mask or unmask the no. of characters specified in the above two parameters

Helper Methods Used

modifyElementUsingXPath(xmlBody, xpath, replaceText,namespace)

This method is used to mask REST XML body and SOAP body.

Table 3.17 Helper Methods Used - modifyElementUsingXPath(xmlBody, xpath, replaceText,namespace)¶

Parameter Description

xmlBody xmlBody can be obtained from the code

xpath xpath, the path should indicate the key whose value should be masked

replaceText The replace value used to mask

namespace

The namespaceURI if the xpath contains namespace prefix ,if there is no namespace prefix in the xpath, then this field can be empty or null

If the xpath contains multiple namespace prefixes then comma separated namespaceURI should be given.

The format for this field is -namespace = prefix1=namespaceUri1,prefix2=namespaceUri2

Note

If replace text is not provided then the value in x-path will be replaced with ****(number of stars will be based on the lenth of the value)

partialMaskingUsingXPath(xmlBody, xpath, namespace, startLen, endLen, maskUnmask)

This method is used to mask REST XML and SOAP XML data partially.

Table 3.18 Helper Methods Used - partialMaskingUsingXPath(xmlBody, xpath, namespace, startLen, endLen, maskUnmask)¶

Parameter Description

xmlBody xmlBody can be obtained from the code using transactionRecording.getXmlBody()

xpath the path should indicate the key whose value should be masked

namespace

The namespaceURI if the xpath contains namespace prefix,if there is no namespace prefix in the xpath, then this field can be empty or null

If the xpath contains multiple namespace prefixes then comma separated namespaceURI should be given.

The format for this field is -namespace = prefix1=namespaceUri1,prefix2=namespaceUri2

startLen No. of starting characters in the jsonPath value to be masked/unmasked

endLen No. of last characters in the jsonPath value to be masked/unmasked

maskUnmask Indicates whether to mask or unmask the no. of characters specified in the above two parameters

Note

If the value for the parameter maskUnmask is mask, then the characters indicated by startLen and endLen will be masked with * and the remaining characters in the value will be unmasked.

If the value for the parameter maskUnmask is unMask, the the characters indicated by startLen and endLen will be unmasked and the remaining characters in the value will be masked with *.

Additionally, there are the following helper methods used for masking in Data Recording:

Table 3.19 Data Recording - Masking Helper Methods¶

Method name Method Description Parameter Parameter Description

modifyElementUsingJsonPath(jsonBody, jsonPath, replaceText) This method is used to mask JSON body jsonBody Json Body can be obtained from the code

jsonPath the path should indicate the key whose value should be masked

replaceText the replace value used to mask

modifyElementUsingXPath(xmlBody, xpath, replaceText) This method is used to mask REST XML body and SOAP body xmlBody xmlBody can be obtained from the code

xpath the path should indicate the key whose value should be masked

replaceText the replace value used to mask

Note

If the xpath contains namespace prefix, then the corresponding namespaceURI should be added in the gateway.properties file.

The format for adding namespace URI in gateway.properties file is: prefix=namespaceURI.

Data Recording Sample Scripts

var obj = new Object();

//to mask json request body
obj.maskJsonRequestBody = function(transactionRecording){

     var maskedJsonBody;
     var jsonBody = transactionRecording.getXmlBody();
     var jsonPath = "$..BSOID";
     var replaceText = "XXXXXXXXXX";
             if(jsonBody  != "" && jsonPath != ""){
                     maskedJsonBody = transactionRecording.modifyElementUsingJsonPath(jsonBody, jsonPath, replaceText);
                     transactionRecording.setXmlBody(maskedJsonBody);
             }

     return transactionRecording;
}

//to mask json response body
obj.maskJsonResponseBody = function(transactionRecording){

     var maskedJsonBody;
     var jsonBody = transactionRecording.getXmlBody();
     var jsonPath = "$..ERROR_CODE";
     var replaceText = "XXXXXXXXXX";
             if(jsonBody  != "" && jsonPath != ""){
                     maskedJsonBody = transactionRecording.modifyElementUsingJsonPath(jsonBody, jsonPath, replaceText);
                     transactionRecording.setXmlBody(maskedJsonBody);
             }

     return transactionRecording;
}

//to mask soap request body
obj.maskRequestBody = function(transactionRecording){

     var maskedxmlBody;
     var xmlBody = transactionRecording.getXmlBody();
     var xpath = "//bss:Provision_Network_Response";
     var replaceText = "XXXXXXXXXX";
             if(xmlBody != "" && xpath != ""){
                     maskedxmlBody = transactionRecording.modifyElementUsingXPath(xmlBody, xpath, replaceText);
                     transactionRecording.setXmlBody(maskedxmlBody);
             }


     return transactionRecording;
}

//to mask soap response body
obj.maskResponseBody = function(transactionRecording){
  var maskedxmlBody;
  var xmlBody = transactionRecording.getXmlBody();
  var xpath = "//bss:ERROR_CODE";
  var replaceText = "XXXXXXXXXX";
      if(xmlBody != "" && xpath != ""){
             maskedxmlBody = transactionRecording.modifyElementUsingXPath(xmlBody, xpath, replaceText);
             transactionRecording.setXmlBody(maskedxmlBody);
      }
 return transactionRecording;
}

//to mask rest xml request body
obj.maskRestXmlRequestBody = function(transactionRecording){

     var maskedxmlBody;
     var xmlBody = transactionRecording.getXmlBody();
     var xpath = "//bsse:STATUS_CODE";
     var replaceText = "XXXXXXXXXX";
             if(xmlBody != "" && xpath != ""){
                     maskedxmlBody = transactionRecording.modifyElementUsingXPath(xmlBody, xpath, replaceText);
                     transactionRecording.setXmlBody(maskedxmlBody);
             }


     return transactionRecording;
}

//to mask rest xml response body
obj.maskRestXmlResponseBody = function(transactionRecording){
  var maskedxmlBody;
  var xmlBody = transactionRecording.getXmlBody();
  var xpath = "//bsse:RESULT_STATUS";
  var replaceText = "XXXXXXXXXX";
      if(xmlBody != "" && xpath != ""){
             maskedxmlBody = transactionRecording.modifyElementUsingXPath(xmlBody, xpath, replaceText);
             transactionRecording.setXmlBody(maskedxmlBody);
      }
 return transactionRecording;
}

Sample script with Examples

Partial masking for JSON data

Consider the below JSON Request payload.

{
  "portIn": {
    "activationDateTime": "2018-11-13T13:20:39-07:00",
    "donor": {
      "accountId": "910001234",
      "subscriptionId": "353123456789",
      "subscriptionType": "POSTPAYMULTILINE"
    }
  }
}

and JSON Response payload

{
  "SOATransactionID": "555454345"
}

Sample script

var obj = new Object();
//for json req
obj.maskJsonRequestBody = function(transactionRecording){

    var maskedJsonBody;
     var jsonBody = transactionRecording.getXmlBody();
     var jsonPath = "$..accountId ";
     var startLen = 1;
     var endLen = 4;
     var maskUnmask = "unMask";
             if(jsonBody  != "" && jsonPath != ""){
                     maskedJsonBody = transactionRecording.partialMaskingUsingJsonPath(jsonBody, jsonPath, startLen, endLen, maskUnmask);
                     transactionRecording.setXmlBody(maskedJsonBody);
             }
     return transactionRecording;
}
//for json res
obj.maskJsonResponseBody = function(transactionRecording){
     var maskedJsonBody;
     var jsonBody = transactionRecording.getXmlBody();
     var jsonPath = "$..SOATransactionID";
     var startLen = 2;
     var endLen = 4;
     var maskUnmask = "mask";
             if(jsonBody  != "" && jsonPath != ""){
                     maskedJsonBody = transactionRecording.partialMaskingUsingJsonPath(jsonBody, jsonPath, startLen, endLen, maskUnmask);
                     transactionRecording.setXmlBody(maskedJsonBody);
             }
     return transactionRecording;
}

The result of the above masking script will be

Masked Request payload:

{
  "portIn": {
    "activationDateTime": "2018-11-13T13:20:39-07:00",
    "donor": {
      "accountId": "9****1234",
      "subscriptionId": "353123456789",
      "subscriptionType": "POSTPAYMULTILINE"
    }
  }
}

Masked Response payload:

{
  "SOATransactionID": "**545****"
}

Partial masking of XML data:

Consider the below REST XML Request payload.

<bsse:Provision_Network_Response xmlns:bsse="http://thbs.com/BSS_Request.xsd">
    <bsse:BSOID>1417_1_1_O2</bsse:BSOID>
    <bsse:RESULT_STATUS>
        <bsse:STATUS_CODE>8</bsse:STATUS_CODE>
    </bsse:RESULT_STATUS>
    <bsse:SO_TYPE>353862205531</bsse:SO_TYPE>
</bsse:Provision_Network_Response>

and REST XML response payload:

<bsse:BSS_Response xmlns:bsse="http://thbs.com/BSS_Response.xsd">
        <bsse:RESULT_STATUS>
                <bsse:STATUS_CODE>0</bsse:STATUS_CODE>
                <bsse:ERROR_CODE>EC02</bsse:ERROR_CODE>
                <bsse:ERROR_DESCRIPTION>Invalid Client</bsse:ERROR_DESCRIPTION>
        </bsse:RESULT_STATUS>
</bsse:BSS_Response>

Sample script

var obj = new Object();
//for rest xml req
obj.maskRestXmlRequestBody = function(transactionRecording){

     var maskedxmlBody;
     var xmlBody = transactionRecording.getXmlBody();
     var xpath = "//bsse:BSOID";
     var namespace  = “bsse=http://thbs.com/BSS_Request.xsd";
     var startLen = 0;
     var endLen = 4;
     var maskUnmask = "unMask";
             if(xmlBody != "" && xpath != ""){
                     maskedxmlBody = transactionRecording.partialMaskingUsingXPath (xmlBody, xpath, namespace, startLen, endLen, maskUnmask);
                     transactionRecording.setXmlBody(maskedxmlBody);
             }

     return transactionRecording;
}
//for rest xml res
obj.maskRestXmlResponseBody = function(transactionRecording){
  var maskedxmlBody;
  var xmlBody = transactionRecording.getXmlBody();
  var xpath = "//bsse:ERROR_DESCRIPTION";
  var namespace  = "bsse=http://thbs.com/BSS_Response.xsd";
  var startLen = 0;
  var endLen = 6;
  var maskUnmask = "mask";
             if(xmlBody != "" && xpath != ""){
                     maskedxmlBody = transactionRecording.partialMaskingUsingXPath (xmlBody, xpath, namespace, startLen, endLen, maskUnmask);
                     transactionRecording.setXmlBody(maskedxmlBody);
             }
 return transactionRecording;
}

The result of the above masking script will be

Masked Request payload:

<bsse:Provision_Network_Response xmlns:bsse="http://thbs.com/BSS_Request.xsd">
    <bsse:BSOID>*******1_O2</bsse:BSOID>
    <bsse:RESULT_STATUS>
        <bsse:STATUS_CODE>8</bsse:STATUS_CODE>
    </bsse:RESULT_STATUS>
    <bsse:SO_TYPE>353862205531</bsse:SO_TYPE>
</bsse:Provision_Network_Response>

Masked Response payload:

<bsse:BSS_Response xmlns:bsse="http://thbs.com/BSS_Response.xsd">
        <bsse:RESULT_STATUS>
                <bsse:STATUS_CODE>0</bsse:STATUS_CODE>
                <bsse:ERROR_CODE>EC02</bsse:ERROR_CODE>
                <bsse:ERROR_DESCRIPTION>Invalid ******</bsse:ERROR_DESCRIPTION>
        </bsse:RESULT_STATUS>
</bsse:BSS_Response>

3.5.8. Configure Endpoints¶

You can have an API Endpoint for the Production environment and one for the Sandbox environment. The production Endpoint is the actual location of the API. The Production environment has active paying subscribers who access APIs via Production Endpoints. Sandbox environment is meant solely for testing the APIs with the intent of learning how to use them. You can call it the “Try-it Out” version of the Production environment. The Sandbox environment, nevertheless, has production-like data and capabilities. Sandbox allows the Consumers to try out APIs via the Sandbox Endpoints before going live and start using the APIs via the Production Endpoints. It is, however, important to know that the Usage Policies set for Sandbox environment are comparatively more rigid.

The DigitMarket™ API Manager Gateway uses a static and a dynamic mode to enable you to route a message to a particular Endpoint. In the static mode, the Endpoints remain the same and cannot be changed. In the dynamic mode, you can provide a script to choose the Endpoint to which you want to route the messages to. DigitMarket™ API Manager allows JavaScript as the scripting language to implement dynamic routing. If the incoming request call needs to be routed to a different Endpoint than the default one, one can provide the required logic in the script, wherein a condition can be set to route the request message to the required backend Resource Endpoint. Based on the routing information in the message header, the request is routed to the required destination.

Note

When you configure Endpoints using the Dynamic Routing scripts, use the Backend Server Name (not the port or IP) to route requests to the required Backend Server.

To configure an Endpoint for Production environment with Static Routing:

Navigate to the API Configuration screen.
Click the Endpoints tab to display the Endpoints tab screen.

Fig. 3.124 Endpoints tab

The Endpoints tab screen has two panels, namely Production and Sandbox. In the Production panel, under Types of Routing, you can find two radio buttons namely, Static Routing and Dynamic Routing.
In Routing, in Type of Routing, click to select the Static Routing radio button to display the Static Routing screen (Static Routing radio button is selected by default, displaying the Static Routing screen).

Fig. 3.125 Static Routing
In Routing, click to Select Backendpoint drop-down box to select the Backend Server for the Production environment. The drop-down lists all the Backend servers that have been added to the Production environment from the Backends main menu option.

Fig. 3.126 Select Backend
In Protocol, click to select between radio buttons HTTP and HTTPS. Selecting HTTPS implies that you want to use SSL security over HTTP.

Fig. 3.127 Select http or https
In Backend Type, click to select between radio buttons REST and SOAP to configure the Backend Type used for the Endpoint.

Fig. 3.128 Select REST or SOAP
The Select the Gateway you want to map drop-down displays the list of Gateways that are configured for the publisher organization. From the Select the Gateway you want to map drop-down, choose the Gateway to which you want to map the API. The Gateways you select will appear at the top of the drop-down. You can remove the selected Gateways by clicking the .

Fig. 3.129 Gateway to Map
Note
- The API Version will be mapped only to the selected Gateways.
- You can also map the API Version from the API tab of the selected Gateway. Refer API.
In the Basepath box, type the base path to be used with the Real Endpoint in the Production environment. The base path is the root path of the Real Endpoint. It precedes the Resource/Operation name and shall be common to all Resources. A URL with base path should resemble the following format:https://myorg-test.dmapim.com/v1/weather/forecast (for HTTPS) and http://myorg-test.dmapim.com/v1/weather/forecast (for HTTP), wherein https://myorg-test.dmapim.com/ (https://myorg-test.dmapim.com/ in the case of HTTP) is the URL fragment that stands for backend server point and /v1/weather is the base path of the Real Endpoint.
Click the Select Endpoint security drop-down box to select a security based on the following options:

None: Select None if you do not wish to have any security for the endpoint.

Linked to Backend: When authentication is linked to the backend, the Gateway replaces credentials in the message header at the subscription-level with the credentials provided at the backend server security-level and the authentication takes place at the backend server-level.

Basic Authentication: When the user selects Basic Authentication, the Gateway authenticates the user credentials (User ID and Password) and then replaces the credentials with the one from the backend security to allow authentication from the backend endpoint-level.

Pass-through: When the user selects pass-through authentication as the API endpoint security, the message is allowed to pass through the Gateway without any processing or alterations and the backend server then authenticates the credentials passed in the message before sending the response back to the client.

WS Security (for SOAP APIs): WS Security behaves similar to Basic Authentication except that it is meant for SOAP messages.

For more information on Authentication, refer: Authentication.

Note

The WS Security option appears when the user is configuring a SOAP API.

Fig. 3.130 Select Endpoint Security for REST APIs

Fig. 3.131 Select Endpoint Security for SOAP APIs

Selecting Basic Authentication or WS Security displays User ID and Password boxes below.

In the User ID and Password boxes that appear below, type a User ID and Password.

Fig. 3.132 Basic Authentication Endpoint Security

You can reveal the password to verify the typed password by clicking to select the check box Show password. Select None if you do not want any security for the Endpoint.

Note

Make sure to uncheck Show password before saving the draft.

Refer To configure Endpoint for Sandbox environment below for instructions on Sandbox panel.
Click Save as Draft to save changes.

For an API Version, if a user selects a Gateway to map, then upon clicking Save as Draft, the application first verifies if in that particular gateway, the selected backend is already mapped or not. If it is not mapped then it will ask if both the backend and the API version has to be propagated automatically.

For better understanding, let us assume that for an API 1, the dependency is Backend 1. Plan 1 also has dependency on API 1. Plan 1 and its dependencies are propagated to Gateway 1. Let us suppose that for a Gateway 2 which has no API mapped to it, a user tries to map API 1 to Gateway 2. The application analyzes that API 1 has dependency on Backend 1. But as the Backend 1 is not mapped to Gateway 2, it too needs to be mapped to Gateway 2. So in this case, system automatically maps both Backend 1 and API 1 to Gateway 2. Under the Endpoints tab of the API Version, both Backend and API can automatically be propagated to the Gateway (if the Backend is not mapped). If the user agrees to the mapping then on the Gateway Sync page, both Backend 1 and API 1 will be available for propagation to Gateway 2. First, Backend 1 has to be propagated and then the API 1 will be propagated to Gateway 2.

If the Backend is not mapped to the Gateway, the application asks for a confirmation as shown below:

Fig. 3.133 Backend Mapping Notification

Click Proceed to confirm the propagation or click Discard to deny the action.

Once the API and backend is approved, they available in gateway sync page for propagation.

To configure an Endpoint for Production environment with Dynamic Routing:

Navigate to the API Configuration screen.
Click the Endpoints tab to display the Endpoints tab screen.

Fig. 3.134 Endpoints tab
In Routing, in Type of Routing, click to select the Dynamic Routing radio button to display the Dynamic Routing screen. Note that the Static Routing radio button is selected by default.

Fig. 3.135 Dynamic Routing sub-tab
In the Script for Dynamic Routing box, type the script that will be used to dynamically route messages to the required Endpoint(s).

Repeat steps 6 and 9 from the above topic, “To configure Endpoint for Production environment in Static mode.”

Refer To configure Endpoint for Sandbox environment below for instructions on Sandbox panel.

Following is the method used in Dynamic Routing script

Table 3.20 Dynamic Routing Method¶
Method name	Method Description
routeRequest()	Use this method to set the actual URI dynamically

Following are the helper methods used in Dynamic Routing script

Table 3.21 Dynamic Routing Helper Methods¶
Method name	Method Description	Parameter	Parameter Description
getHeaderValue(key)	Use this method to get http header value for the incoming request	key	key passed in http request header
setTarget(protocol, backendName, basePath)	Use this method to set the actual URI for the real backend	protocol	should be http or https
		backendName	Name of the Backend where the request will be processed
		basePath	Actual Base URL

Dynamic Routing Sample script

var obj = new Object();
obj.routeRequest = function(dynamicRouting)
{
  var headerValue = dynamicRouting.getHeaderValue("X-SSL-client-s-dn");
  var result = headerValue.split("CN=");
  StringFinalHeaderVal = result[result.length-1];
  if(StringFinalHeaderVal == "PERF")
    {
      dynamicRouting.setTarget("http,ThbsOSBPerf,/sim/autostub/Enterprise/JaxwsWebservice/jaxwsWebservice");
      }else{
      dynamicRouting.setTarget("http,ThbsOSBSoap,/sim/autostub/Enterprise/Webservice/jaxwsWebservice");
     }
   return dynamicRouting;
}

Note

When a dynamic routing script has backend server dependencies, make sure to propagate all the backend server to the relevant Gateways mapped to the API version.

3.5.9. Add Advanced Configurations¶

The Advanced tab in the API Configuration screen allows you to specify the time for request timeouts, set fault message details and response cache for REST and SOAP APIs.

3.5.9.1. Setting Request Timeout¶

You can configure as to how long the Gateway can wait for an API request to be serviced before giving up. If a response is not sent within the time specified by you, a request timeout message is sent back.

Timeout can be set at the API version-level and/or the Resource/Operation-level. When you set timeout at the API version-level, the value that you provide applies commonly to all the Resource/Operation endpoints for the API version being configured. For Resource/Operation-level timeout setting, you specify the timeout value for each Resource/Operation separately.

To set Request timeout for a REST API:

Navigate to the API Configuration screen.
Click the Advanced tab to display the Advanced tab screen.

Fig. 3.136 Advanced tab

The Timeout sub-tab is the default sub-tab. The Timeout sub-tab has two panels, namely, Version Level and Resource Level.
In the Version Level panel, in the Timeout Value box, type the timeout value (in milliseconds) that you want to allocate at the version level.
In the Resource Level/Operation Level panel, under each Resource/Operation name listed, in the box provided, type the Timeout value in ms (milliseconds).
Click Save as Draft to save changes.

To set Request timeout for a SOAP API:

Navigate to the API Configuration screen.
Click the Advanced tab to display the Advanced tab screen.

The Timeout sub-tab is the default sub-tab. The Timeout sub-tab has two panels, namely, Version Level and Operations level.

Fig. 3.137 Timeout sub-tab
In the Version Level panel, in the Timeout Value box, type the timeout value (in milliseconds) that you want to allocate to all Operations at the version level.
In the Operations Level panel, in the Timeout Value box, type the Timeout value in milliseconds that you want to allocate for each Operation in the API.
Click Save as Draft to save changes.

3.5.9.2. Setting Fault configuration¶

You can overwrite the default fault configuration at Version level and at Resource/Operation level for individual resources/operations.

Refer Set Global Configurations for information on setting global configurations for faults/errors.

Note

Upon any changes in the artifacts, the artifacts needs to be repropagated.

To set fault configuration for a REST API:

Navigate to the API Configuration screen.
Click the Advanced tab to display the Advanced tab screen. The Timeout sub-tab is the default sub-tab.
Click the REST Fault sub-tab to display the REST Fault sub-tab screen.

Fig. 3.138 REST Fault sub-tab
Click to expand the Default Fault Content Type tab. You can overwrite the configured Content Type at Version Level and for individual Resources at Resource level. Click the Overwrite toggler to activate overwrite. Click the toggler again to disable it.

Fig. 3.139 Default Content Type
Click to select the required Content Type JSON/XML/PlainText to be configured at Version Level and for each individual Resources at Resource level and then click Save as Draft to save the changes.
Next, click to expand the Default Fault Structure tab. You can overwrite the configured Fault Structure at Version level and for individual Resources at Resource level. Click the Overwrite toggler to activate overwrite. Click the toggler again to disable it.

Fig. 3.140 Default Fault Structure
(Optional) Edit the JSON/XML/Plain Text Fault box to make any required changes to the Fault template at Version level and for individual resources at Resource level and then click Save as Draft to save the changes.
Next, click Scenario-wise Fault Message tab. You can overwrite the configured Fault Message at Version level and for individual resources at Resource level. Click the Overwrite toggler to activate overwrite. Click the toggler again to disable it.

Fig. 3.141 Scenario-wise Fault Message
(Optional) Click the Response Code box corresponding to the Fault scenario to type in a different fault code in the box.
(Optional) Click the HTTP Code box corresponding to the Fault scenario to type in a different HTTP code in the box.
(Optional) Click the Fault Message Content box corresponding to the Fault scenario to type in a different Fault Message in the box.
Click Save as Draft to save the changes.

To set fault configuration for a SOAP API:

Navigate to the API Configuration screen.
Click the Advanced tab to display the Advanced tab screen. The Timeout sub-tab is the default sub-tab.
Click the SOAP Fault sub-tab to display the SOAP Fault sub-tab screen.

Fig. 3.142 SOAP Fault sub-tab
Click to expand the Default Fault Structure accordion tab. You can overwrite the Default Fault Structure at Version level and for individual operations at Operation level. Click the Overwrite toggler to activate overwrite. Click the toggler again to disable it.

Fig. 3.143 Default Fault Structure
(Optional) Edit the XSD Fault box to make any required changes to the Default Fault Structure at Version/Operation Level and then click Save as Draft to save the changes.
Next, click to expand the Scenario-wise Fault Message accordion tab. You can overwrite the configured Fault Message at Version level and for individual Operations at Operation level. Click the Overwrite toggler to activate overwrite and click again to disable it.

Fig. 3.144 Scenario-wise Fault Message

(Optional) Click the Response Code box corresponding to the Fault scenario to type in a different fault code in the box.
(Optional) Click the HTTP Code box corresponding to the Fault scenario to type in a different HTTP code in the box.
(Optional) Click the Fault Message Content box corresponding to the Fault scenario to type in a different Fault Message in the box.
Click Save as Draft to save the changes.

3.5.9.3. Setting Response Cache¶

Response caching is a storing mechanism used to deal with repeated requests for the same resource. Storing response in a cache reduces the number of requests the client or proxy will make to the backend, thereby reducing the load on the backend. When a client sends a request to the backend for the first time, the Gateway will fetch the response from the backend. This response is stored in a cache for a specific time interval. During that time interval, if a request comes from the same client, the Gateway will fetch the response from the cache instead of the backend.

Users can set response cache at both version level and at resource level. If response cache is enabled at version level, then it will automatically be applicable to all resources. If the user does not wish to set response cache for all resources or if they want to configure different response cache settings for individual resources, then they can do so using the Override option. If the user clicks the override option for a resource, the response cache settings for that particular resource can be configured separately.

Note

For the first request coming for a resource, response will always come from the backend.
Response caching is applicable only to GET resources for REST APIs and POST operations for SOAP APIs.

3.5.9.3.1. Setting Response Cache for REST API¶

To set response cache for a REST API:

Navigate to the API Configuration screen.

Click the Advanced tab and then click Response Cache sub-tab. The Response Cache sub-tab displays the response cache settings at version level and resource level. For REST API, only GET resources will be displayed.

Fig. 3.145 Response Cache

When you create an API, the response cache will be disabled by default. If you add a resource after enabling the response cache at version level, then the response cache will be enabled for the newly added resource. You can enable/disable response cache at version level for all resources. These settings can be overriden at resource level for specific resources.

Response cache at version level

To enable response cache at version level, click Response Cache toggle button. Inversely, click Response Cache toggle button again to disable it.
In the Cache refreshes in field, enter the time interval after which the response cache will be cleared.
Click Save as Draft to save changes.

Fig. 3.146 Version level Response Cache

Any changes made to response cache settings at version level, will by default be applicable to all the resources. You can override the response cache settings configured at version level for specific resources at resource level.

Response cache at resource level

To override response cache at resource level, for the required resource, click Override toggle button. Inversely, click Override toggle button again to disable it.
If response cache is not set, click Turn response cache toggle button to enable it for a particular resource. Click it again to disable it.
In the Cache refreshes in field, for the required resource, enter the time interval after which the response cache will be cleared.
Click Save as Draft to save changes.

Fig. 3.147 Resource level Response Cache

Any changes made to response cache settings at version level will not affect the response cache settings of resources overriden at resource level.

Note

Response cache gets updated whenever the data is propagated or when a new resource is added to the REST API.

3.5.9.3.2. Setting Response Cache for SOAP API¶

To set response cache for a SOAP API:

Navigate to the API Configuration screen.

Click the Advanced tab and then click Response Cache sub-tab. The Response Cache sub-tab displays the response cache settings at version level and operation level. For SOAP API, only POST operations will be displayed.

Fig. 3.148 Response Cache

When you create an API, the response cache will be disabled by default. If you add an operation after enabling the response cache at version level, then the response cache will be enabled for the newly added operation. You can enable/disable response cache at version level for all operations. These settings can be overriden at operation level for specific operations.

Response cache at version level

To enable response cache at version level, click Response Cache toggle button. Inversely, click Response Cache toggle button again to disable it.
In the Cache refreshes in field, enter the time interval after which the response cache will be cleared.
Click Save as Draft to save changes.

Fig. 3.149 Version level Response Cache

Any changes made to response cache settings at version level, will by default be applicable to all the operations. You can override the response cache settings configured at version level for specific operations at operation level.

Response cache at operation level

To override response cache at resource level, for the required resource, click Override toggle button. Inversely, click Override toggle button again to disable it.
If response cache is not set, click Turn response cache toggle button to enable it for a particular operation. Click it again to disable it.
In the Cache refreshes in field, for the required operation, enter the time interval after which the response cache will be cleared.
Click Save as Draft to save changes.

Fig. 3.150 Operation level Response Cache

Any changes made to response cache settings at version level will not affect the response cache settings of operations overriden at operation level.

Note

Response cache gets updated whenever the data is propagated or when a new operation is added to the SOAP API.

3.5.10. Add API Versions¶

DigitMarket™ API Manager allows you to manage more than one version of an API. The Add Versions option provided in the API Action menu action of the API Configuration screen enables you to create newer versions of an existing API. By default, DigitMarket™ API Manager displays the most recent version of an API in the API Configuration screen. A newly created API is automatically allotted the first version number, i.e., 1. You can find the version number displayed alongside the API State in the API Configuration screen.

Fig. 3.151 API version

To add a new version of an existing API version:

Navigate to the API Configuration screen.
In the API Configuration screen, click the Action icon . The API Action menu displays.

Fig. 3.152 API action menu
In the drop-down menu that displays, click Add Version. The Add API Version dialog box displays.

Fig. 3.153 Add API version dialog
In the Version Number box, type a version number. You can add version numbers in decimal increments, such as 8.1, 8.2, and so on, to denote minor revisions or increment it to the next number for major changes like version upgrades, say from Version 1.0 to 2.0.

Note

The Version number should be in the format 2.0, 3.0, 3.2, etc.
In the Version Notes box, type Version notes. The Version notes that you type here gets automatically populated in the Version Notes box in the Overview tab of the API Configuration screen.
Click the Copy From Version drop-down list to select an earlier version to copy content from.

Fig. 3.154 Copy from API version

The Copy From Version drop-down list displays all the previous versions of the API plus the currently open version. Alternatively, you can choose None to add a version without duplicating the data.
Click Add to finish adding a new version. In the Action menu, the new version gets added to the Versions list under VERSIONS. The API Configuration screen updates itself to display data from the newly created version.

If you have created a newer version by copying from an earlier version, the newly created version displays the content from the earlier version. In case you chose None while creating a version, an unedited/non-configured version of API displays, wherein you need to add fresh data.

Note

You can add newer Versions for an existing API irrespective of the State of the original API version, i.e., Draft, Approved, Published, Deprecated or Retired State.

You can switch versions to start working on a version other than the newly created version. You will learn more about switching API versions in the next topic.

3.5.10.1. Switch API Versions¶

If there are more than one Version of an API, you can switch versions to work on another version of the API.

To switch versions of an API:

Navigate to the API Configuration screen.
In the API Configuration screen, click the Action icon to display the API Action menu. The menu displays all the available versions under VERSIONS.

Fig. 3.155 API versions
Click to select the version that you want to work on. The API Configuration screen updates itself to display data from the selected API version.

3.5.11. Manage Visibility of an API¶

You can determine which Publisher Group(s) is allowed access to an API Version. This behavior is controlled using the Visibility settings of Publisher Groups.

To learn more about the Visibility feature, refer: User Roles and Portal Visibility.

To learn how to add a Publisher Group, visit the section: Manage Publisher Users and Groups.

To set Visibility for an API:

Navigate to the API Configuration screen.
In the API Configuration screen, click the Action icon to display the API Action menu.

Fig. 3.156 API Action menu
In the API Action menu, under ACTIONS, click Manage Visibility to open API Visibility dialog box. The API Visibility dialog box displays the current list of Publisher groups.

Fig. 3.157 API Visibility dialog
Click to select the check box(es) corresponding to the Groups to which you want to provide access to the currently open API Version.

Fig. 3.158 API Visibility - select Groups
Click Submit to save changes and close the dialog box.

Note

The Manage Visibility feature is not available for users with business user roles.

3.5.12. Edit an API Name¶

You can change the name of an API irrespective of its API State.

To edit an API name:

Navigate to the API Configuration screen.
In the API Configuration screen, click the Action icon . The API Action menu displays.
Click Edit API Name to display the Edit API Name dialog box.

Fig. 3.159 Edit API name dialog
Click Submit to save changes and close the dialog box.

3.5.13. Send an API for Approval¶

An API version that is newly created and edited is saved as a draft. This is indicated by its State displayed alongside the version number in the API Configuration screen.

Fig. 3.160 API lifecycle state

A draft API has to be sent for approval. After the approval the API’s State changes to the Approved state, which can then be synced to the Gateways to turn it to the Published state. Only Approved and Published APIs are made available for bundling into API Packs.

To send an API for Approval:

Navigate to the API Configuration screen.
In the API Configuration screen, click the Action icon . The API Action menu displays. If the logged-in user has the automatic workflows enabled, the API Action menu displays Approve under STATES as the API does not then need to be sent for approval. If the logged-in user has the automatic workflows disabled, the API Action menu displays Submit for Approval under STATES as the API goes through the manual approval workflow.
On the Action menu, under STATES, click Submit for Approval to submit the draft API for approval (for manual workflows) or click Approve to approve the draft API (for automatic workflows) .

Fig. 3.161 Approve API

Fig. 3.162 Submit API for approval

If automatic Approval Workflow for logged-in user role is enabled: The API state changes from Draft to Approved.

If automatic Approval Workflow for logged-in user role is disabled: The API state changes from Draft to Submitted for Approval. The API’s State changes from Submitted for approval to Approved when a Publisher user approves the API.

Fig. 3.163 Approved state

An approved API changes to a Published API once it is synced to the Gateways. You can select resources/operations from an approved or Published API for creating API Packs.

Note

Make sure you have filled all the required fields in the Overview, Resources, and Endpoints tabs before sending the API version for approval.

Note

You cannot directly make changes to an approved or Published API version. To make changes to an approved or Published API version, you must make use of the Submit Version For Edit option available from the Action menu of the API Configuration screen. You can avail this option only when the API version is in the approved or Published State.

To learn about the Open for Edit feature, visit: Open an Approved or Published API for Editing

3.5.14. Deprecate an API¶

You can deprecate an API version if you have added newer or better methods or changed fields in a newer version. However, you may need to keep the older API version operational and allow API calls to be made to the older API version. Ideally, you would want to keep a deprecated API version operational until the consumers make their transition to the newer version.

Deprecated APIs act as a forewarning to the Consumers to start upgrading to newer versions as Deprecated APIs are marked for Retirement and can be phased out of use.

Resources/Operations from a deprecated API are not available for adding into a new API Pack, although they continue to be available to consumers for making API calls.

The option for submitting an API for Deprecation becomes available once the State of the API changes to Approved or Published. In other words, you can only deprecate an Approved or Published API.

Note

An API that is approved lies in the Gateway Sync to be propagated to the Gateway. To deprecate the API, you must first remove the API from the Gateway Sync.

To deprecate an API:

Navigate to the API Configuration screen.
On the Action menu, under STATES, click the Action icon . The API Action menu displays. The menu options will have the “Submit for Deprecation” (for manual Workflows) or “Deprecate” (for automatic Workflows) option if the API is approved or published and its state displays as Approved or Published.
Click Submit for Deprecation (for manual Workflows) to send the API you want to Deprecate for approval or click Deprecate (for automatic Workflows) to deprecate the API.

Fig. 3.164 Submit API for deprecate

Fig. 3.165 Deprecate API

A warning message appears asking you to confirm your action.

Fig. 3.166 Warning for Deprecating an API
Click OK to proceed or click Cancel to exit. When you click OK a cofirmation message will pop-up.

Fig. 3.167 Warning for Deprecating an API

The API Version’s State changes from

Approved to Approved.Submitted For Deprecation for manual Workflows and Approved to Deprecate for automatic Workflows.

Fig. 3.168 Approved Submitted For Deprecation

Published to Published.Submitted For Deprecation for manual Workflows and Published to Deprecate for automatic Workflows.

Fig. 3.169 Published Submitted For Deprecation

For manual Workflows, after a designated Publisher user approves the API, the API’s State changes from Submitted For Deprecate to Deprecated.

Note

A Deprecated API is not available for selection while creating an API Pack.

Note

You are not allowed to make changes to deprecated APIs as the save option is available only for APIs in their Draft states.

3.5.15. Retire an API¶

You can retire deprecated versions of APIs. The need to retire an API version may arise when an updated version of the API becomes available. Resources/Operations from a retired API are not available for bundling into API Packs, and hence do not get exposed for making API calls.

The option for submitting an API version for Retirement becomes available once the state of an API version changes to the Deprecated state.

Note

If any Resource/Operation from a Deprecated API version is being used in any of the Packs, the API version is not permitted to be retired.

To retire an API version that has its resources/operations added to an API Pack, you need to first unlink/remove these resources/operations from the Pack content before you can retire the API version.

To Retire an API:

Navigate to the API Configuration screen.
Click the Action icon . The API Action menu displays. The menu options will have the “Submit for Retirement” (for manual Workflows) or Retire (for automatic Workflows) option if the API is deprecated and its state displays as Deprecated.
On the Action menu, under STATES:

For manual workflow:
- Click Submit For Retirement to send the API you want retired for approval. The API state changes from Deprecated to the Submitted For Retirement. When a Publisher user approves the “Approvals request” for an API, the API’s State changes from Submitted For Retirement to Retired.
Fig. 3.170 Submit API for Retirement

Once we click on Submit For Retirement the API state will change to Submitted for Retirement.

Fig. 3.171 Submitted for Retirement

Once the Submit For Retirement is approved the API state will change to Retired.

Fig. 3.172 Retired

For automatic workflow:

Click Retire to retire the API.

Fig. 3.173 Retire API

A warning message appears asking you to confirm your action.

Fig. 3.174 Warning for Retiring an API

Click OK to proceed or click Cancel to exit.

The API state changes from Deprecated to Retired.

Fig. 3.175 Retired

Note

You are not allowed to make changes to a Retired API.

Note

A Retired API is not available for creating an API Pack.

3.5.16. Open an Approved or Published API for Editing¶

An API version that is in its approved or published state is locked for editing; meaning that you cannot make any direct changes to such API versions. To make changes to such APIs, you need to use an option from the API Action menu called Submit Version For Edit.

The Submit Version For Edit option allows the user to perform the task given below:

If Automatic Approval Workflow is disabled, send an Approved or Published API version for edit approval, which allows you to edit the API after the approval.
If Automatic Approval Workflow is enabled, change the API version to the Draft state, which allows you to edit the API right away.

To Submit an Approved or Published API for Edit (when automatic workflow is disabled):

Navigate to the API Configuration screen.
Click the Action icon . The API Action menu displays. The menu options will have the Submit Version For Edit option if the API is in its Approved or Published State.
In the Action menu, under STATES, click Submit Version For Edit. The API State changes to Approved, Awaiting Approval for Editing or Published, Awaiting Approval for Editing, as the case may be (Published, Awaiting Approval for Editing is applicable when automatic workflow is disabled).

Fig. 3.176 Open API for edit

Once approved, the state of the API changes back to the Draft state. You can now go ahead and edit the API.

When you are done with making changes to the API version, submit the API for approval. After the approval is done, the State of the API changes to the Approved State.

To put the changes into effect, complete the steps enumerated in the Gateway Sync section. Gateway Sync makes the changed APIs operational.

3.5.17. Discard Changes after opening an API for Editing¶

You can discard the draft changes made and revert to the earlier approved or published API Version. Doing this nullifies any change that has been made while revising the API version after opening it for Editing.

To Discard the Draft after opening an API for editing:

Navigate to the API Configuration screen.
Click the Action icon . The API Action menu displays. The menu options will have the Discard Draft option if the API Version is in its Draft State after approval for Open for Editing.
In the Action menu, under STATES, click Discard Draft.

Fig. 3.177 Discard changes

The API Version state reverts to the Approved or Published state and the approved or published API Version; before the last Open for Editing, is restored.

3.5.18. Search an API¶

The user can search for an API using the Search feature present in the API list pages. To learn more about the Search feature, refer the topic: Search in Product Introduction>Key Concepts.

The search results page displays matches for the search from the following API components:

API Name
Overview (all components)
Resource Name
Resource Description
Resource Specification (Swagger or WSDL file name)
API Backend names
Version Names
Version Notes
API Endpoint details

To search for an API:

Navigate to the API List page.
In the search box, type in the keyword(s) for starting a search on an API or one of its components.

Fig. 3.178 Search API
Click the Search icon to display the search results.

Fig. 3.179 Search results

Each entry in the Search result page takes the following format for displaying matches:
```
<API Name><API Type>

<Version name> <State>
<matches>...

<Version name><State>
<matches>...
```
For example, a search for the word ‘world’ in the API List returns:
```
Calendar API

V1.0 [Published]

Overview: ... provides the world calendar...

Resources: /world/location
```

Next Steps

In the next section, you will learn to export and import approved or published APIs.