Sending Queries

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

Axon Synapse only supports request-response queries. It’s unable to take care of scatter-gather and subscription queries at this moment.
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]/queries/[queryName] pattern. The content of the HTTP request is the serialized query. 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 is the payload type)

  • AxonIQ-ResponseType: the expected response type (required when the handler uses Axon Framework)

  • AxonIQ-ResponseCount: use MULTIPLE to indicate that the query handler can return multiple instances of the response type

The code below represents a sample request to the http-raw endpoint sending an io.axoniq.demo.giftcard.api.FetchCardSummariesQuery.

POST http://synapse:8080/v1/contexts/default/queries/io.axoniq.demo.giftcard.api.FetchCardSummariesQuery
Content-Type: application/xml
AxonIQ-ResponseType: io.axoniq.demo.giftcard.api.CardSummary
AxonIQ-ResponseCount: MULTIPLE

<io.axoniq.demo.giftcard.api.FetchCardSummariesQuery>
    <offset>0</offset>
    <limit>100</limit>
</io.axoniq.demo.giftcard.api.FetchCardSummariesQuery>

When Axon Synapse processes this HTTP request, it sends the query to Axon Server on behalf of the client application. Axon Server then delegates the query to a query handler registered in the default context. When the handler responds with a zero or more io.axoniq.demo.giftcard.api.CardSummary objects, Axon Synapse serializes the payload and sends it back in the response payload of the HTTP request.

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

The http-message endpoint

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

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

{
  "payload": "<io.axoniq.demo.giftcard.api.FetchCardSummariesQuery><offset>0</offset><limit>100</limit></io.axoniq.demo.giftcard.api.FetchCardSummariesQuery>"
  "name": "io.axoniq.demo.giftcard.api.FetchCardSummariesQuery",
  "responseType": "io.axoniq.demo.giftcard.api.CardSummary"
}

The message may contain additional optional fields like payloadType and metaData. You can use the payloadType field to specify the payload type in cases where the query name doesn’t equal the payload type for the query message.

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 to 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": {
   "offset": 0,
   "limit": 100
   },
  "name": "io.axoniq.demo.giftcard.api.FetchCardSummariesQuery",
  "responseType": "io.axoniq.demo.giftcard.api.CardSummary"
}

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