Sending Events

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

You can only pass metaData using the http-message or http-list-of-messages endpoints. 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]/events/[eventName] pattern. The content of the HTTP request is the serialized event. 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-AggregateId:

  • AxonIQ-AggregateType:

  • AxonIQ-SequenceNumber:

  • AxonIQ-DateTime:

The code below represents a sample request to the http-raw endpoint sending a local.application.client.Event.

POST http://synapse:8080/v1/contexts/default/events/local.application.client.Event
Content-Type: application/json
AxonIQ-AggregateId: 901aa5ce-b281-4788-97f2-2be7f236dde6
AxonIQ-AggregateType: Aggregate
AxonIQ-SequenceNumber: 0
AxonIQ-DateTime: 2022-09-22T21:37:00.000+00:00

{
   "id": "901aa5ce-b281-4788-97f2-2be7f236dde6",
   "text": "New customer created"
}

When Axon Synapse processes this HTTP request, it publishes an event to the Axon Server on behalf of the client application. Axon Server stores the event in the default context of the event store as specified in the request’s URL.

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

The http-message endpoint

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

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

{
  "payload": {
    "id": "901aa5ce-b281-4788-97f2-2be7f236dde6",
    "text": "New customer created"
  },
  "name": "local.application.client.Event",
  "aggregateId": "901aa5ce-b281-4788-97f2-2be7f236dde6",
  "aggregateType": "Aggregate",
  "sequenceNumber": 0,
  "dateTime": "2022-09-22T21:37:00.000+00:00"
}

The JSON payload may contain additional optional fields such as metaData. Again when Axon Synapse receives such an HTTP request, it publishes an event to Axon Server on behalf of the client application, which stores it in the default context.

For more details about the http-message endpoint, please refer to the Publish Event Message API docs (select application/json request body schema).

The http-list-of-messages endpoint

This is technically the same endpoint as http-message one above. It uses the same URL path pattern of /v1/context/[contextName]/events. The difference is in the content type. While for the http-message, it’s application/json, and for the http-list-of-messages, it’s application/vnd.axoniq.event.list+json. This content type indicates the JSON payload is a list (named items) of events instead of a single event. Below is a sample request in http-list-of-messages form.

POST http://synapse:8080/v1/contexts/default/events
Content-Type: application/vnd.axoniq.event.list+json

{
"items": [
  {
    "payload": {
      "id": "901aa5ce-b281-4788-97f2-2be7f236dde6",
      "text": "New customer created"
    },
    "name": "local.application.client.Event",
    "aggregateId": "901aa5ce-b281-4788-97f2-2be7f236dde6",
    "aggregateType": "Aggregate",
    "sequenceNumber": 0,
    "dateTime": "2022-09-22T21:37:00.000+00:00"
  },
  {
    "payload": {
      "id": "901aa5ce-b281-4788-97f2-2be7f236dde6",
      "text": "Customer moved"
    },
    "name": "local.application.client.Event",
    "aggregateId": "901aa5ce-b281-4788-97f2-2be7f236dde6",
    "aggregateType": "Aggregate",
    "sequenceNumber": 1,
    "dateTime": "2022-09-22T21:37:01.000+00:00"
  }
  ]
}

When Axon Synapse receives such an HTTP request, it publishes the event to Axon Server on behalf of the client application.

For more details about the http-list-of-messages endpoint, please refer to the Publish Event Message API docs (select application/vnd.axoniq.event.list+json request body schema).