Pub/sub topic patterns

Publication and subscription patterns let you declare what topics each endpoint should be allowed to publish messages to or to receive them from.

A single access pattern may cover multiple topics, possibly including ones that do not exist at the time of an endpoint's creation, and it is customary to arrange topic names and their respective permission patterns in hierarchical structures, going from the broadest elements to the more specific ones using a slash / for the separator, akin to file paths in a file-system.

Special symbols that can be used in patterns are:

*AsteriskMatches zero or more characters, excluding the slash
**Two asterisksMatches zero or more characters, including the slash

Supposing there are several topics ..

/usa/va/richmondEvents related to Richmond, Virginia, USA
/usa/va/washingtonEvents related to Washington, Virginia, USA
/customer/address/changedNotifications about changed addresses of customers in a company's CRM
/customer/telephone/changedNotifications about changed telephones of customers in a company's CRM
/customer/telephone/deletedNotifications about deleted telephones of customers in a company's CRM

.. it is possible to create various access patterns depending on the intended purpose:

/usa/va/richmondBecause it does not use special symbols, this matches that exact topic name
/usa/**Matches any topics related to the USA, i.e. any that starts with this prefix
/usa/va/*Matches any topics related to Virginia, USA. Currently, it would match Richmond and Washington but should another topic be added, such as /usa/va/arlington, it will be also matched in run-time even if this topic did not exist at the time when the endpoint was created or last edited.
/usa/*/richmondMatches any Richmond city in the USA
/customer/**Matches all topics related to customers in the CRM
/customer/*/changedMatches all topics related to changes in customers
/customer/telephone/*Matches all topics related to changes or deletions related to customer telephones

Note that patterns are specified separately for publications and subscriptions and that there must be a matching role for the pattern to be taken into account at all, i.e. if an endpoint has publication rights to a topic but its role is a Subscriber then it will not be able to publish the message despite correct access rights. This can be used to temporarily revoke publication or subscription rights without a need to redefine permissions.

In the example below, a REST endpoint called CRM is of a Publisher/Subscriber role. It uses credentials defined in a HTTP Basic Auth security 'pubapi'. It is allowed to publish to all topics matching pattern /usa/va/* but it is not allowed to subscribe to messages from these topics. It is, however, allowed to both publish and subscribe to messages matching pattern /customer/*/changed.

Creating an endpoint and giving it rights to publish is sufficient for this endpoint to begin publications immediately, there is no other step needed. To receive messages, however, a subscription needs to be created first.

Getting started

Using publish/subscribe