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.

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
}