Content based routing

If your API is hosted at multiple endpoints, you can use the Content based routing protocol to send requests to the correct endpoint based on the content of the request message.

This capability lets you determine which operation a consuming application has requested and route complex requests to an endpoint on a faster machine. If the entry protocol is HTTP or HTTPS, select Content based routing to route requests based on the rules you define and configure authentication for incoming requests.

In IBM API Studio, the kind Route identifies this policy.

Example of a Content based routing policy: 

kind: Route
apiVersion: api.ibm.com/v1
metadata:
  name: contentBasedRouting
  version: 1.0
  namespace: dev
spec:
  default-endpoint:
    $ref: dev:default_endpoint:1.0
  content-based-endpoints:
    - payloadIdentifier:
        xpath: '/xpath'
        namespaces:
        - prefix: 'ns1'
          URI: 'http://uri1'
        - prefix: 'ns2'
          URI: 'http://uri2'
      endpoint:
        $ref: dev:content_based_endpoint1:1.0
    - payloadIdentifier:
        jPath: '/jsonpath'
      endpoint:
        $ref: dev:content_based_endpoint2:1.0
    - payloadIdentifier:
        regex: '*regex'
      endpoint:
        $ref: dev:content_based_endpoint3:1.0
---
kind: HTTPEndpoint
apiVersion: api.ibm.com\v1
metadata:
  name: default_endpoint
  version: 1.0
spec:
  url: http://localhost:3000/
  method: GET
  connectTimeout: 300
  readTimeout: 200
  sslConfig:
    keyStoreAlias: ""
    keyAlias: ""
    trustStoreAlias: ""
  serviceRegistryParameters:
    - name: ""
      value: ""
---
kind: HTTPEndpoint
apiVersion: api.ibm.com\v1
metadata:
  name: content_based_endpoint
spec:
  url: http://localhost:4000/
  method: GET
  connectTimeout: 300
  readTimeout: 200
  sslConfig:
    keyStoreAlias: ""
    keyAlias: ""
    trustStoreAlias: ""
  serviceRegistryParameters:
    - name: ""
      value: ""

To invoke the Content based routing policy, you can specify:

Code view Form view Description
spec Endpoint reference In the form view, you can use the Add endpoint button to specify the endpoint details.
  • default-endpoint. Specifies the URI of the native API endpoint to route the request to.

  • content-based-endpoints. Define a list of content-based routing rules that map specific payload values to target endpoints.

    Configure the following specs:

    • payloadIdentifier. Specify the payload identifier to locate the client, extract the custom authentication credentials from the request, and verify the client’s identity.
      You can use the following payload types:
      • jPath. Specify the JSONPath expression to extract values from a JSON payload.

      • XPath. Specify the XPath expression to extract values from an XML payload.

        Specify these details under namespaces:

        • prefix. Specify the namespace prefix of the payload expression to be validated.
        • URI. Specify the namespace URI of the payload expression to be validated.
    • regex. Specify a regular expression to match values in the payload for routing.
    • end-point. Specify the URI of the content-based endpoint to route the request to.

      This endpoint is provided as $ref value in the format $ref: namespace : content-based-endpoint name: version.

To configure the default-endpoint and content-based-endpoint, use the kind: HTTPEndpoint to specify the endpoint details:

Type Description
spec This denotes various asset properties that you can configure for the endpoint.

These are the endpoint specifications that can be configured:

  • URL. Specifies the URL for the default endpoint.
  • method. Specifies the available routing methods.
  • connectTimeout. Specifies the number of seconds after which connection timeout is initiated.
  • readTimeout. Specifies the number of seconds after which read timeout is initiated.
  • sslConfig. Specifies the SSL configurations.
    You can configure the following SSL details:
    • keyStoreAlias. Specify the keystore alias to identify the API call. This value (along with the value of Client Certificate Alias) is used for conducting an SSL client authentication.
    • keyAlias. Specify the alias of the private key, which should reside in the keystore specified by the keystore alias.
    • trueStoreAlias. Specify the alias for the truststore containing CA certificates used by IBM API Studio to validate the native API’s SSL certificate.

  • serviceRegistryParameters. Specify values that are used for constructing the discovery service URI. Configure the name and value.