Receive Messages with Postman

You learned how to send messages to Axon Synapse in the previous section. In this one, you’ll listen to messages from Axon Synapse. Again the three message types you can listen for are commands, queries, and events.

Prerequisites

To accomplish the steps in this guide, you need to download and install Axon Synapse, Axon Server, and the Giftcard demo application. Before you continue, please complete the steps detailed on the Installation page.

Additionally, you need to download and install Postman. Go to Postman’s download page for detailed instructions.

Postman mock servers

When you send messages to Axon Synapse, you send HTTP requests. To receive messages, Axon Synapse sends HTTP requests to your application. You may create such an application in any language. From Axon Synapse’s perspective, all that matters is that it can receive an HTTP request and process the message in the payload.

For the purposes of this example, you’ll simulate your application by using Postman’s mock server feature.

Handle a command message

A command message is a request to perform a specific operation. Axon Synapse sends such messages via regular HTTP requests.

Create a dedicated mock server

Select Mock Servers in Postman’s sidebar, then select +.

A screenshot of the first step of creating the query handling mock in the Postman

Figure 1. A screenshot of the first step of creating the command handling mock in the Postman

Next, give it a name. You can leave default values in other options.

Figure 2. A screenshot of the second step of creating the command handling mock in the Postman

The new mock server is ready and waiting for incoming messages.

A screenshot of the query handling mock in the Postman

Figure 3. A screenshot of the command handling mock in the Postman

Configure Axon Synapse to send commands to the mock server

You must inform Axon Synapse what commands it should send to the application (the mock server in this case). Sending a registration request to Axon Synapse, as demonstrated below, is one way to do it.

(1) (2) (3)
POST http://localhost:8080/v1/contexts/default/handlers/commands
Content-Type: application/json

{
  "names": [
    "io.axoniq.demo.giftcard.api.IssueCardCommand" (4)
  ],
  "endpoint": "https://cb5b8a7d-d2d1-4583-a6bc-31c70e9d0593.mock.pstmn.io/gift-cards", (5)
  "endpointType": "http-raw", (6)
  "clientId": "Postman", (7)
  "componentName": "Giftcard" (8)
}

1	POST - indicates a POST request
2	`http://localhost:8080` - the instance of Axon Synapse
3	`v1/contexts/default/handlers/commands` - registering a command handler
4	`io.axoniq.demo.giftcard.api.IssueCardCommand` - the command name
5	The command handler endpoint, in this example the Postman mock
6	The command handler endpoint type (`http-raw` means the payload is in the request’s body)
7	The unique identifier of the command handling application instance
8	The application of the application component

Alternatively, you can use Axon Synapse’s UI to register the handler.

Figure 4. A screenshot of registering the command handling mock in the Synapse UI

Confirm it works

If you configured the mock server correctly, there are now two command handlers in the system for the IssueCardCommand message. There is one in the Giftcard demo app and the Postman mock server you created. As new command messages of type IssueCardCommand arrive, they’re load-balanced between the two handlers.

Go to the admin page for the Giftcard demo app and issue several new gift cards. Doing so creates and sends several IssueCardCommand command messages. At least some of them should go to Postman mock server. Once it receives such a command, you should see the content of the command and its meta-data, as on the screen below.

Figure 5. A screenshot of a command captured by the Postman mock

Handle a query message

A query message is a request for information and so the handler must respond. Responding to a query message received from Axon Synapse is nothing more than replying to the HTTP request. You’ll use a Postman mock server again to simulate the behavior of an HTTP application.

Create a dedicated mock server

Select Mock Servers in Postman’s sidebar, then select +.

Figure 6. A screenshot of the first step of creating the query handling mock in the Postman

For the Response Body, you can use the template sown below.

<list> (1)
    <io.axoniq.demo.giftcard.api.CardSummary> (2)
        <id>http-based-gift-card</id> (3)
        <initialValue>155</initialValue> (4)
        <remainingValue>155</remainingValue> (5)
    </io.axoniq.demo.giftcard.api.CardSummary>
</list>

1	The response with list of gift cards
2	The first gift card
3	The `id` property
4	The `initialValue` property
5	The `remainingValue` property

Proceed to the next step and give the mock a name.

Figure 7. A screenshot of the second step of creating the query handling mock in the Postman

Finally, you can listen to requests:

Figure 8. A screenshot of the query handling mock in the Postman

Go to the Collections tab and add headers to the response:

AxonIQ-PayloadType: java.util.ArrayList

Figure 9. A screenshot of the header view for query handling mock in the Postman

Configure Axon Synapse to send queries to the mock server

You need to register the query handler with Axon Synapse as you did with the command handlers. The code below shows an example of doing so via the HTTP API.

(1) (2) (3)
POST http://localhost:8080/v1/contexts/default/handlers/queries
Content-Type: application/json

{
  "names": [
    "io.axoniq.demo.giftcard.api.FetchCardSummariesQuery" (4)
  ],
  "endpoint": "https://ac365f15-964b-4083-af93-1536f297fd7e.mock.pstmn.io/list-gift-cards/", (5)
  "endpointType": "http-raw", (6)
  "clientId": "Postman", (7)
  "componentName": "Giftcard" (8)
}

1	POST - indicates a POST request
2	`http://localhost:8080` - the instance of Axon Synapse
3	`v1/contexts/default/handlers/queries` - creating a query handler
4	`io.axoniq.demo.giftcard.api.FetchCardSummariesQuery` - the query name
5	The query handler endpoint, in this example the Postman mock
6	The query handler endpoint type (`http-raw` means the payload is in the request’s body)
7	The unique identifier of the command handling application instance
8	The application of the application component

Alternatively, you can use Axon Synapse’s UI to register the handler.

Figure 10. A screenshot of registering the query handling mock in the Synapse UI

Confirm it works

Again, if you configured everything correctly, there are two query handlers for the FetchCardSummariesQuery - the one from the Giftcard demo app and the one from Postman’s mock server. Therefore, routing a query to the mock server may take several tries.

You can test the query handler using the Giftcard demo app or Synapse HTTP query.

Figure 11. A screenshot of a query result returned by the Postman mock in the Giftcard demo application UI

Handle an event message

Axon Synapse can send events to your application through HTTP requests, one by one, ordered by the sequence index.

Create a dedicated mock server

Create a new Mock Server in the Postman.

Figure 12. A screenshot of the first step of creating the event handling mock in the Postman

Figure 13. A screenshot of the second step of creating the event handling mock in the Postman

Figure 14. A screenshot of the event handling mock in the Postman

Configure Axon Synapse to send events to the mock server

As with the other message types, you must register the event handler in Axon Synapse. Below is an example of the HTTP API approach.

(1) (2) (3)
POST http://localhost:8080/v1/contexts/default/handlers/events
Content-Type: application/json

{
  "names": [
    "io.axoniq.demo.giftcard.api.CardIssuedEvent" (4)
  ],
  "endpoint": "https://1d5cae3d-b328-4565-a36b-2d4a49de79de.mock.pstmn.io/card-issued", (5)
  "endpointType": "http-raw", (6)
  "clientId": "Postman", (7)
  "componentName": "Giftcard" (8)
}

1	POST - indicates a POST request
2	`http://localhost:8080` - the instance of Axon Synapse
3	`v1/contexts/default/handlers/events` - creating an event handler
4	`io.axoniq.demo.giftcard.api.CardIssuedEvent` - the event type
5	The event handler endpoint, in this example the Postman mock
6	The event handler endpoint type (`http-raw` means the payload is in the request’s body)
7	The unique identifier of the event-handling application instance
8	The application of the application component

Similarly to the earlier examples, you can use Synapse UI.

Figure 15. A screenshot of registering the event handling mock in the Synapse UI

Confirm it works

As soon as you register the event handler, you should see the events in Postman’s mock server window.

Figure 16. A screenshot of an event captured by the Postman mock