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 two cornerstone 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.

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",
        "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"
}
$

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