Receiving Commands

Any service available at an accessible URL can be a command handler. Synapse can send commands to such services via HTTP requests. The service must be able to handle requests containing commands. A command handler may return a response message or send a status without a body.

Endpoint types

Axon Synapse can send HTTP requests containing commands in two different ways. Each endpoint that registers as a command handler must support one of them.

http-raw

Axon Synapse serializes a single command directly into the HTTP request’s body when interacting with http-raw endpoints. It provides all other relevant information in the HTTP headers of the request:

  • Content-Type

  • AxonIQ-MessageId

  • AxonIQ-CommandName

  • AxonIQ-PayloadType

  • AxonIQ-Priority

Please refer to the API documentation for detailed information about the HTTP request structure.

http-message

When interacting with http-message endpoints, Axon Synapse generates a JSON message that contains the serialized command and all information related to the command. It then sends that JSON message in the HTTP request’s body.

Please refer to the API documentation for detailed information about the HTTP request structure.

Registering command handlers

Command handlers must explicitly register in Axon Synapse to receive commands from Axon Server. There are two ways to register a command handler - using Synapse’s Web interface or through the Synapse HTTP API.

In both cases, Axon Synapse needs the following information:

Command names

a list of names for the commands that this handler can handle

Client ID

unique id for the handler application instance

Component name

a logical name for the handler application

HTTP Endpoint

the URL of the handler

Endpoint Type

specifies whether the handler expects a raw or message request type

Endpoint Options

any key/value pairs that Axon Synapse should include in requests to the handler (as HTTP headers)

Load Factor

relative weight for this handler, if there are multiple handlers for a command, handlers with a higher load factor get a higher percentage of the requests.

For a full list of parameters, including optional ones, please refer to the API documentation.

Registering a command handler via Axon Synapse UI

To register a command handler via Axon Synapse UI, go to Command Handlers  Register new command handler and fill in the form:

Screenshot of the Axon Synapse UI for registering a new command handler

Registering a command handler via Axon Synapse API

To register a command handler via Axon Synapse API, send a JSON request to the respective endpoint. You can find detailed information about the endpoint in the API documentation.

Below is a sample JSON request to register a handler:

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

{
  "names": [
    "local.application.client.Command"
  ],
  "endpoint": "https://client.application.local/v1/message",
  "endpointType": "http-raw",
  "endpointOptions": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "clientId": "application-name-7c78946494-p86ts",
  "componentName": "application-name",
  "loadFactor": 100,
  "concurrency": 1,
  "enabled": true
}

Concurrency control

For a given command handler, synapse allows you to specify the maximum amount of concurrent requests, Synapse calls your application with. You can achieve this by setting the maxConcurrency parameter for a given registration.

Synapse does however never send you two concurrent requests for the same routing key. This allows you not to keep track of ordering of concurrent requests. However, this also might lead to lower rates of concurrent processing than specified in the maxConcurrency parameter. The decision-making whether Synapse may send a request concurrently, works in the following order: 1. ensure there are less than maxConcurrency requests already ongoing. 2. ensure there is no other request running for the current routingKey.

While this may allow a lot of requests for the same routingKey block processing for commands of a different routing key that arrive later and Synapse could forward it, this approach the safest and most defensive one.

Note that the maxConcurrency parameter refers to the maximum amount of concurrent requests. Depending on your routing key, your application might observe a lower amount of concurrency (see section above).