Sending Commands

Any application that can not connect directly to Axon Server can still send commands through Axon Synapse’s HTTP APIs. This document explains the two ways to do so.

Axon Server routes commands based on a routing key in the request. If multiple handlers exist for the same command, Axon Server sends requests with the same routing key to the same handler. Command handlers often rely on the routing consistency provided by routing keys to cache data between requests.
You can only pass metaData using the http-message endpoint. The http-raw endpoint doesn’t provide a way to do so.

The http-raw endpoint

The http-raw endpoint URL path follows the /v1/context/[contextName]/commands/[commandName] pattern. The content of the HTTP request is the serialized command. The sender may provide additional information through HTTP headers.

There is one required header:

  • Content-Type: the serialization type for the context

The following headers are optional:

  • AxonIQ-PayloadType: defines the type of the payload (if missing, the command name as the payload type)

  • AxonIQ-Priority: priority of the request (default is 0, a higher value means higher priority)

  • AxonIQ-RoutingKey: the key used for routing (auto-generated if missing) The code below represents a sample request to the http-raw endpoint sending an io.axoniq.demo.giftcard.api.IssueCardCommand.

POST http://synapse:8080/v1/contexts/default/commands/io.axoniq.demo.giftcard.api.IssueCardCommand
Content-Type: application/xml

<io.axoniq.demo.giftcard.api.IssueCardCommand>
  <id>sample-card-5</id>
  <amount>110</amount>
</io.axoniq.demo.giftcard.api.IssueCardCommand>

When Axon Synapse processes this HTTP request, it sends the command to Axon Server on behalf of the client application. Axon Server then delegates the command to a command handler registered in the default context.

For more details about the http-raw endpoint, please refer to the Send Command API docs.

Message endpoint

The http-message endpoint URL path follows the /v1/context/[contextName]/commands pattern. The content of the HTTP request is a JSON message containing all the information for a single command. Below is the above request in http-message form.

POST http://synapse:8080/v1/contexts/default/commands
Content-Type: application/json

{
  "payload": "<io.axoniq.demo.giftcard.api.IssueCardCommand><id>sample-card-5</id><amount>110</amount></io.axoniq.demo.giftcard.api.IssueCardCommand>"
  "name": "io.axoniq.demo.giftcard.api.IssueCardCommand"
}

The message may contain additional optional fields like payloadType, routingKey, priority, and metaData.

The serialization format of the query object must match the serialization the query handler expects. Even though the HTTP payload is JSON, if the query handler expects XML, the payload must be XML. If the handler expects a JSON serialized payload, the request would be:

POST http://synapse:8080/v1/contexts/default/commands
Content-Type: application/json

{
  "payload": {
   "id": "sample-card-5",
   "amount": 110
   },
  "name": "io.axoniq.demo.giftcard.api.IssueCardCommand"
}

For more details about the http-raw endpoint, please refer to the Send Command Message API docs.