Pub/sub - API - REST

Overview

If you're new to the publish/subscribe pattern, start with What is publish/subscribe?

Before making use of the REST pub/sub API, a REST endpoint needs to be created with HTTP Basic Auth credentials and appropriate permissions.

REST integration with publish/subscribe is built around three operations:

• To make use of any of these endpoints, a REST client must use HTTP Basic Auth credentials previously assigned to it by Zato admins

• REST clients can subscribe to topics if they have proper subscription permissions. Subscribing to the same topic multiple times is safe and has no effect. All messages from all subscribed topics are delivered to a single queue per user.

  • REST clients receive their messages in one of two ways:
    • Pull-style: clients call /pubsub/messages/get to retrieve messages on demand
    • Push-style: Zato delivers messages to configured REST endpoints as soon as they arrive

OpenAPI definition

• In your Dashboard at http://localhost:8183, click EDA → Download OpenAPI to download the complete specification of the interface, for instance, to generate API clients from it, or to use it with tools such as Postman

• You can also download the specification from GitHub

Demo credentials, topics and subscriptions

• In your Dashboard at http://localhost:8183, click EDA → Import test config to auto-configure demo credentials, and a few topics, so that you can quickly try out the REST API

• The demo credentials are user.1/password.1

• Note that the test config does not survive container restarts and it's meant to be used during development and testing, for your convenience, but the configuration is real, your actual credentials or topics will look similarly

Publishing messages

Topic name must be provided in the URL path. Message data and optional parameters are given as JSON payload.

Request

Response

Samples

OK, data sent and message ID returned:

$ curl -XPOST http://user.1:password.1@localhost:11223/pubsub/topic/orders.processed \
  -d '{"data":"Order #12345 has been processed", "priority": 7}'
{
  "is_ok": true,
  "cid": "correlation-id-123",
  "msg_id": "zpsm.20250829-074432-7264-d47439a9f-abc",
  "status": "200 OK"
}
$

Error, no data sent on input:

$ curl -XPOST http://user.1:password.1@localhost:11223/pubsub/topic/orders.processed \
  -d '{}'
{
  "is_ok": false,
  "cid": "correlation-id-456",
  "details": "Invalid request data",
  "status": "400 Bad Request"
}
$

Getting messages from queues

Messages from all subscribed topics are retrieved through a single endpoint. Optional parameters control the number and size of messages returned.

Each retrieved message stays in the queue until the client acknowledges it through /pubsub/messages/ack:

1. A call to /pubsub/messages/get hands the messages out to this client and reserves them for 30 seconds, during which no other call receives them.
2. The client processes the messages and sends their msg_id values to /pubsub/messages/ack, which removes them from the queue.
3. A message that was not acknowledged within the 30 seconds is handed out again by the next call to /pubsub/messages/get. A response that never reached the client, for instance because the connection was lost, therefore loses no messages.

A client that processes the same message twice with the same result needs no further precautions. Otherwise, it records the msg_id of each processed message and skips a message whose msg_id it already processed. The reservation period is set through the Zato_PubSub_Pull_Lease_Seconds environment variable of the server.

Request

Response

Message metadata fields

Samples

OK, multiple messages returned:

$ curl -XPOST http://user.1:password.1@localhost:11223/pubsub/messages/get \
  -d '{"max_messages": 5}'
{
  "is_ok": true,
  "cid": "correlation-id-789",
  "messages": [
    {
      "data": {
        "order_id": 12345,
        "status": "completed"
      },
      "meta": {
        "topic_name": "orders.processed",
        "size": 45,
        "priority": 5,
        "expiration": 3600,
        "msg_id": "zpsm.20250829-074432-7264-d47439a9f-abc",
        "delivery_attempt": 1,
        "correl_id": "order-12345",
        "pub_time_iso": "2025-01-01T12:00:00+00:00",
        "recv_time_iso": "2025-01-01T12:00:01+00:00",
        "expiration_time_iso": "2025-01-01T13:00:00+00:00",
        "time_since_pub": "0:00:30.123456",
        "time_since_recv": "0:00:30.123456"
      }
    }
  ],
  "message_count": 1,
  "status": "200 OK"
}
$

OK, no messages available:

$ curl -XPOST http://user.1:password.1@localhost:11223/pubsub/messages/get
{
  "is_ok": true,
  "cid": "correlation-id-101",
  "messages": [],
  "message_count": 0,
  "status": "200 OK"
}
$

Error, no subscription found for user:

$ curl -XPOST http://user.1:password.1@localhost:11223/pubsub/messages/get
{
  "is_ok": false,
  "cid": "correlation-id-102",
  "details": "No subscription found for user",
  "status": "401 Unauthorized"
}
$

Acknowledging messages

Messages retrieved from a queue are removed from it when the client acknowledges them by their msg_id values.

Request

Response

Samples

OK, both messages acknowledged:

$ curl -XPOST http://user.1:password.1@localhost:11223/pubsub/messages/ack \
  -d '{"msg_ids": ["zpsm.20250829-074432-7264-d47439a9f-abc", "zpsm.20250829-074433-1182-a03b5c71e-abc"]}'
{
  "is_ok": true,
  "cid": "correlation-id-103",
  "ack_count": 2,
  "status": "200 OK"
}
$

OK, the messages were already acknowledged earlier:

$ curl -XPOST http://user.1:password.1@localhost:11223/pubsub/messages/ack \
  -d '{"msg_ids": ["zpsm.20250829-074432-7264-d47439a9f-abc"]}'
{
  "is_ok": true,
  "cid": "correlation-id-104",
  "ack_count": 0,
  "status": "200 OK"
}
$

Data format

• All requests and responses use JSON format
• Authentication is always with HTTP Basic Auth
• All responses include an is_ok boolean field indicating success or failure
• All responses include a cid field for correlation tracking
• Error responses include a details field with error description
• Success responses include a status field with HTTP status description

Success response example:

{
  "is_ok": true,
  "cid": "correlation-id-123",
  "status": "200 OK"
}

Error response example:

{
  "is_ok": false,
  "cid": "correlation-id-456",
  "details": "Authentication failed",
  "status": "401 Unauthorized"
}

Topic name restrictions

• Maximum length: 200 characters
• Only ASCII characters are permitted
• The "#" character is not allowed
• Topic names are case-insensitive

Getting started with EDA

Using EDA