5 Set Up Custom APIs

Create a Custom API

You can access the TM Forum (TMF) Open APIs using the proxy endpoints provided by the application. You can use these APIs in various scenarios to support your business needs. You can also deploy TMF or non-TMF APIs for your communications application by using CX Industries Framework APIs.

For example:

  • You can add a custom TMF API, which adheres to the TMF Open API structure, to perform address validation for tax calculation by setting it to connect with taxation gateway.
  • You can add a Siebel non-TMF API, which follows the open API standards, to get a catalog by setting it to connect with Siebel.

Note:

You can use TMF APIs to route requests and publish events. However, you can use the non-TMF APIs only to route requests.

Here's how you create a third-party API or a custom API:

  1. Create the payload for registering the custom API with the details described in this table.
    Field Description
    api-name The name of the user-defined API.
    api-version The version of the API.
    openapi-document-url A link to the document that describes the API (optional).
    api-id The identifier of the API, for example, siebel-100.
    alternative-root-path The alternative URL path.
    api-events The name of the event that you want to publish through this API, such as individualCreateEvent.
    api-resources
    • The name of the resource you want to associate with this API, such as Individual.
    • The ID and path to that resource, for example, /individual.

    Note:

    You must add at least one resource for the API.
  2. Call the apis API by running this cURL command or by using a REST API client:

    curl-H Authorization: Bearer <accessToken> https://<hostName>/admin/{workspace}/apis/ -X POST -H "Content-Type: application/json" -d @api-data.json

    Where:

    • <accessToken> is the OAuth access token for your account.
    • <hostName> is the URL for your CX Industries Framework API Gateway.
    • <workspace> is the path parameter for the production or test workspace. For example, 02 for the test workspace and 01 for the production workspace. If you are calling the API using FA API Gateway, you can skip this parameter.

    The API returns a response with the custom API ID. You can associate this API with an external application to route requests generated by this API to that application. For more information, see Related Topics.

    Here is a sample request payload for registering a custom API:

    {
"api-name": "siebel",
"api-version": "v1",
"openapi-document-url": "https://wolpertinger/.	",
"api-id": "siebel-100",
"alternative-root-path": "siebel/v1.0", "api-events" : [],
"api-resources": [
{
"name": "workflow-process-manager", "resource-id": "res-1",
"resource-path": "service/Workflow Process Manager/RunProcess"
},
{
"name": "price-list",
"resource-id": "res-2",
"resource-path": "data/Price List/Price List",
"routing-ambiguity-resolution-strategy": "HTTP400BadRequest" # To mention the required Routing Ambiguity type, to be defined per resource , if not defined will be considered a default HTTP400BadRequest
},
{
"name": "price-list-by-id",
"resource-id": "res-3",
"resource-path": "data/Price List/Price List/{id}/Price List Item", "path-parameters": [
{
"parameter-name": "id", "parameter-type": "string", "optional" : false
}
]
},
{
"name": "swi-product-class", "resource-id": "res-4",
"resource-path": "service/SWI Product Class/QueryByExample"
},
{
"name": "swi-product-attributes", "resource-id": "res-5",
"resource-path": "service/SWI Product Attributes/QueryByExample"
},
{
"name": "swi-catalog-admin", "resource-id": "res-6",
"resource-path": "service/SWI Catalog Admin/QueryByExample"
},
{
"name": "swi-product",
"resource-id": "res-7",
"resource-path": "service/SWI Product/QueryByExample"
}
]
}

Related Topics

Add Custom API to System Description

If you want the custom API to interact with an existing external application, you must update the system description to add your custom APIs. You use the systemDescriptors API to update this description.

Note:

Ensure that you don't update default system descriptors and connection descriptors to integrate any new external application. To replace a pre-integrated target application with an external application, create new descriptors by using the POST method of systemDescriptors and connectionDescriptors APIs. In case, if you lose a default system descriptor or connection descriptor, create a service request on My Oracle Support to revert your changes.

If you're using the custom API in a complete new integration, see Integrate External Applications chapter in this guide. Here's how you can add the custom API to the existing system descriptor:

  1. Create a payload with the target application details. You can create the payload by copying the application's systemdescriptor and adding the new custom API in the "offered-apis" section along with the url-prefix for the API.
  2. Call the systemDescriptors API by running the following curl command or by using a REST API client:
    curl -H Authorization: Bearer <accessToken https://<hostName>/admin/{workspace}/systemDescriptors/{id} -
X PUT -H "Content-Type: application/json" -d @api-data.json

where:

  • <accessToken> is the OAuth access token for your account.
  • <hostName> is the URL for your CX Industries Framework API Gateway.
  • <workspace> is the path parameter for the production or test workspace. For example, 02 for the test workspace and 01 for the production workspace. If you are calling the API using FA API Gateway, you can skip this parameter.

The API returns the response with an accepted status if the descriptor is updated.

Let's consider this example where you're updating the system description for Siebel to add a custom API for getting the product catalog.

Here is a sample request payload for the getCatalog API that you add to the system description by using the systemDescriptors API:

{
"target-name": "siebel", "external": {
"apis": [
{
"api-id": "siebel-100",
"api-version": "v1", "api-resources": [
{
"resources": [
{
"resource-id": "res-1"
},
{
"resource-id": "res-2"
},
{
"resource-id": "res-3"
},
{
"resource-id": "res-4"
},
{
"resource-id": "res-5"
},
{
"resource-id": "res-6"
},
{
"resource-id": "res-7"
}
]
}
]
}
]
},
"system" : "siebel", "domain" : "siebel"
}

Create Routing Criteria

You can use the existing routing criteria created for the target application to route requests or create a new routing criteria.

Here's how you can create the routing criteria:

  1. Create the payload for creating the routing criteria with the required details. For more information, see Routing Criteria.
  2. Call the routingCriteria API by running this cURL command or by using a REST API client:
    curl -H Authorization: Bearer <accessToken> https://<hostName>/admin/{workspace}/routingCriteria/ -X PATCH BY ID <ID> -H
"Content-Type: application/json" -d @api-data.json

    Where:

    • <accessToken> is the OAuth access token for your account.
    • <hostName> is the URL for your CX Industries Framework API Gateway.
    • <workspace> is the path parameter for the production or test workspace. For example, 02 for the test workspace and 01 for the production workspace. If you are calling the API using FA API Gateway, you can skip this parameter.
    • <ID> is the identifier of the routing criteria that you are updating.

The API creates the routing criteria and returns its ID. Make note of this ID and enter it as criterion-link in the gatekeeper rule created for the target application.

Routing Criteria

You can use any of these criteria for routing requests using the non-TMF APIs:

Table 5-1 Criteria for Different Routing Requests

Criteria Description
Boolean

Evaluates whether a condition is true or false. If it's set to true, the application considers that the condition is true. The valid values are true and false.

Example:

{
"boolean-criterion": {
"description": "The always passing criterion",
"value": true
}
}
HTTP Header

Evaluates inbound request headers based on the specified criteria. You can use values or regular expressions in this criteria.

Note: You can't use both values and regular expressions in the same criteria.

Here are the fields you can use in this criteria:

  • header-criteria: The type of the criteria. If you add multiple objects in the same header criteria, all of them must evaluate to true.
  • request-header-name: The name of the header key.
  • header-value-one-of: A list of strings to validate the header values.
  • ecma262-regex-value: The JavaScript regular expression to validate the header values.
  • header-backend-handling: The header value handling type. If set to routing-only, the application doesn't share the header with the target application. If set to pass-through, the application passes the header to the target application.

Example:

{
"header-criteria": [
{
"request-header-name": "end-system", "header-value-one-of": [
"siebel", "fa"
],
"header-backend-handling": "routing-only"
},
{
"request-header-name": "test",
"ecma262-regex-value": "^[a-z]{4,10}$", "header-backend-handling": "routing-only"
}
]
}
Query Parameter

Evaluates the inbound HTTP request query parameters based on the specified criteria. You can use values or regular expressions in this criteria.

Note:You can't use both values and regular expressions in the same criteria.

Here are the fields you can use in this criteria:

  • query-param-criteria: The type of the parameter.
  • query-parameters: A list of supported parameters. If you add multiple objects in the same criteria, all the objects must evaluate to true.
  • query-parameter-name: The name of the query parameter.
  • query-parameter-value-one-of: A list of string values to validate the query parameter values.
  • ecma262-query-parameter-regex: The JavaScript regular expression to validate the query parameter values.
  • parameter-nature: The query parameter handling type. If set to routing-only, the application doesn't share the header with the target application. If set to pass-through, the application passes the header to the target application.
Example:
{
"query-param-criteria": { "description": "Model1", "query-parameters": [
{
"query-parameter-name": "target-system", "query-parameter-value-one-of": [ "siebel",
"fa"
],
"parameter-nature": "pass-through"
},
{
"query-parameter-name": "test",
"ecma262-query-parameter-regex": "^[a-z]{4,10}$", "parameter-nature": "routing-only"
}
]
}
}
HTTP Method

Evaluates inbound HTTP request method based on the methods specified in the criteria. The valid values are HTTP methods, such as GET, POST, PUT, and DELETE.

Example:

{
"http-method-criteria": { "description": "description", "http-methods": [
"GET", "POST"
]
}
}
Expression

Evaluates request based on the expressions specified in the criteria. For information on the expressions, operators, and keywords that you can use in this criteria, see the Gatekeeper Criteria topic in this guide.

Example:

{
"expression-criteria": [
{
"expression-string": "target-system pr and target-system eq buying"
},
{
"expression-string": "OP eq GET"
}
]
}

You can group these criteria using the any-criteria-of condition. When you group the criteria, the API routes the request only if at least one of the criteria evaluates to true. For example: 

{
"any-criteria-of": [
{
"http-method-criteria": { "description": "description", "http-methods": [
"GET", "POST"
]
},
"query-param-criteria": { "query-parameters": [
{
"query-parameter-name": "target-system", "query-parameter-value-one-of": [
 

"siebel", "fa"
],
"parameter-nature": "pass-through"
}
]
}
},
{
"http-method-criteria": { "http-methods": [
"PUT", "DELETE"
]
}
}
] }
}
],
"criteria-link-key": "fa criteria"
}

In this example, the API routes the requests only if one of the following conditions evaluates to true:

  • HTTP Method of the input request is either GET or POST and target-system is present with either siebel or fa as its value.
  • HTTP Method of the input request is either PUT or DELETE.

Note:

When you use the any-of-criteria condition, you must specify the criteria-link-key in the payload. Ensure that it is unique and readable. You can use this link key to reuse the criteria.

You can reuse an existing criteria and group it with any new criteria by using ref-criterion. Here's an example with the reference criterion: 

{
"any-criteria-of": [
{
"ref-criterion": { "criteria-refs": [ "Buying Query Params",
"Buying Criteria Expression"
]
}
}
],
"criteria-link-key": "Reference Criteria"
}

In this example, the API routes the request only if both the criteria BuyingQuery Params and BuyingCriteria Expression evaluate to true.

Review Gatekeeper Rules

If you want to use this custom API for routing requests or publishing events, you must review and update the target application's gatekeeper rule to include this API.

Note:

You can use only APIs that follow TMF Open API structure for publishing events.

If you have added a non-TMF API, you must add the Destination Selection details. This includes API ID, version, resources that belong to this API, and the criteria for publishing events.

Here's an example:

"destination-selection": [
{
"api-id": "siebel-200",
"api-version": "v1",
"include-in-sparse-query-results":{
"enabled": true # To specify if the Gatekeeper is interested in Routing Ambiguity or not , to be defined per api
},
"criteria": [
{
"rank": 14,
"resource-ids": [ "res-0"
]
},
{
"rank": 39,
"resource-ids": [
"res-1",
"res-2",
"res-3",
"res-4",
"res-5"
],
"criterion-link": "UNI1648100823"
}
]
}
]
}

If you have only a single gatekeeper and that gatekeeper supports all the resources belonging to the non-TMF API, then you need not define any criteria or specify the resources. You can just add the following:

"destination-selection": [ { "api-id": "Siebel-200", "api-version": "v4", "criteria": [ { "rank": 50 } ] } ]

If you have added a TMF API, you can skip the Destination Selection details and update only the gatekeeper rules. To review and update the gatekeeper rule for a custom API, see Update Gatekeeper Rules.