Receiving Queries

Any service available at an accessible URL can be a query handler. Synapse can send events to such services via HTTP requests. The service must be able to handle requests containing queries and respond to them.

Endpoint types

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

http-raw

Axon Synapse serializes a single query 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-QueryName

  • AxonIQ-PayloadType

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 containing the serialized query and all related information. 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 query handlers

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

In both cases, Axon Synapse needs the following information:

Query 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)

Registering a query handler via Axon Synapse UI

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

"Screenshot of the Axon Synapse UI for registering a new query handler

Registering a query handler via Axon Synapse API

To register a query 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/queries
Content-Type: application/json

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