Skip to main content

Mocking Webservice APIs with Listeners

You may need to implement orchestration flows that depend on custom or third-party APIs that do not exist, that you cannot access, or for which you do not have sufficient details to invoke. In such cases, you can orchestrate using API mocking, and replace the mocks when you have sufficient information about the actual Webservice APIs that you need to use. Alternatively, this recipe explains how you can use Conscia DX Engine’s Listener capabilities to mock Webservice APIs. The Listener described in this recipe simply returns the JSON body passed to the Listener. You may choose to implement functional Components in your API mocking Template, and you may implement multiple Templates to mock multiple APIs.

Overview​

Conscia DX Engine Listeners respond to HTTP traffic at specific unique URLs. Listeners are often used as endpoints for webhooks from other systems. You can read the documentation about Conscia DX Engine Listeners here:

To mock an Webservice API with a Listener, you need to:

  • Implement an Orchestration Component that mocks the Webservice API.
  • Implement an Orchestration Template that includes that Component.
  • Implement a Listener that invokes that Template.

Conscia Listeners require an Orchestration Template, and a Template requires an Orchestration Component. In this example, the Component does nothing, and the Template simply includes that Component. You can implement an empty Conscia Object Mapper Component and a Template that includes that Component.

Implementation Details​

To create a Listener that can mock APIs, you can POST a Listener definition to the /api/listeners Conscia Webservice that registers Listeners. For a sandbox environment, you can use this URL to register Listeners:

  • https://engine-staging.conscia.io/api/listeners

Remember to pass the Content-Type, Authorization, or X-Customer-Code HTTP headers to Conscia DX Engine Listeners.

To update that Listener, PATCH the body to the same URL, adding the Listener identifier as the last step in the URL path:

  • https://engine-staging.conscia.io/api/listeners/{listenerCode}

The following HTTP body registers a synchronous Listener with the identifier named Mocks APIs with the identifier mock-APIs that responds to POST HTTP requests by invoking the Template with identifier mock-api.

{
    "listener": {
        "listenerCode": "mocks-apis",
        "name": "Mocks APIs",
        "sync": true,
        "endpointRequestSpec": {
            "methods": [
                "POST"
            ]
        },
        "engineRequest": {
            "templateCode": "mock-api",
            "context": {}
        },
        "endpointResponse": {
            "status": 200,
            "body": "`requestBody`",
            "headers": [
                {
                    "header": "Content-Type",
                    "value": "application/json"
                }
            ]
        }
    }
}

Specifically, the body key causes the Listener to return the JSON body posted to the Listener:

"body": "`requestBody`",

The API that creates the Listener returns a success message and the definition of the Listener including its unique ID and URL path Component:

{
    "message": "Successfully created Listener",
    "listener": {
        "listenerCode": "mocks-apis",
        "name": "Mocks APIs",
        "sync": true,
        "endpointRequestSpec": {
            "methods": [
                "POST"
            ]
        },
        "engineRequest": {
            "templateCode": "mock-api",
            "context": {}
        },
        "endpointResponse": {
            "status": 200,
            "body": "`requestBody`",
            "headers": [
                {
                    "header": "Content-Type",
                    "value": "application/json"
                }
            ]
        },
        "@listenerUuid": "bea0bfc8-c591-4f7e-a8a8-bfeb5a50e096",
        "@listenerPath": "73616e64626f782d6a6f686e77657374:70726576696577/bea0bfc8-c591-4f7e-a8a8-bfeb5a50e096"
    }
}

Use the value of @listenerPath from the result of this Webservice API to determine the URL of the Listener. If @listenerPath is the following value:

73616e64626f782d6a6f686e77657374:70726576696577/bea0bfc8-c591-4f7e-a8a8-bfeb5a50e096

Then the URL of this Listener in a sandbox is:

  • https://engine-staging.conscia.io/api/experience/_listener/73616e64626f782d6a6f686e77657374:70726576696577/bea0bfc8-c591-4f7e-a8a8-bfeb5a50e096

You do not need to pass the Content-Type, Authorization, or X-Customer-Code HTTP headers to Conscia DX Engine Listeners.

If you POST the following body to this API mocking Listener:

{
  "key": "value"
}

Conscia returns that post body:

{
  "key": "value"
}

Retrieve Listener Definition Including Unique ID and URL Path Component​

You can use the /api/listeners Conscia Webservice API to retrieve a Listener’s definition, unique ID, and URL path Component. For a sandbox environment, you can GET the following URL to retrieve a Listener definition, replacing {listenerCode} with the identifier you specified when you created the Listener:

  • https://engine-staging.conscia.io/api/listeners/{listenerCode}

The result of this API uses the same format as that returned when you created the Listener.

Alternatives​

Numerous SaaS API mocking solutions are available on the Internet.

A free alternative such as webhook.site or even pastebin is enough.

You could use a Conscia Universal API Connector Component to invoke the Conscia Webservice API used to invoke Orchestration Templates and Orchestration Components that would contain the values.

You might be able to use a Component that responds with static values:

You can use Data Transformation Script Orchestration Components to mock APIs.