SEMP Features
This section provides more details about the SEMP v2 features discussed in SEMP API Architecture:
-
The
select
query parameter allows you to specify which data fields to include in or exclude from query results. -
The
where
query parameter lets you include only results that match certain criteria. -
You can retrieve the number of objects certain collections.
-
You can retrieve the number of messages in a queue, topic endpoing, or replay log.
-
The Opaque Password provides a mechanism for including write-only attributes in responses.
-
Paging is the mechanism by which query results are divided into discrete pages to limit the size of the data returned.
In addition, some operations are not supported:
-
Rate Limiting is not provided with the SEMP API. We recommend managing the frequency of requests you send.
-
Transactions are not supported directly, but individual requests either complete successfully or not at all.
-
Sorting query results is not supported.
Returning Selected Data Fields
You can use the select
query parameter to include only the specified attributes of the object in the response, or to exclude the specified attributes of the object from the response. Use this query parameter to limit the size of the returned data for each returned object, return only those fields that are desired, or exclude fields that are not desired.
The select
query parameter can be used to limit what attributes are returned in a response, but it does not force an attribute to be returned if it otherwise would not have been.
select
The value of select
is a comma-separated list of attribute names. Names may include the *
wildcard (zero or more characters). Nested attribute names are supported using periods (e.g., parentName.childName
). The question mark character, "?", with the typical meaning of matching a single character, is not supported.
Attribute names take the following form:
<attribute-name> = ["-"] <attribute-string> 0*n( "." <attribute-string> ) ; attribute name, possibly nested, possibly preceded by "-"
At most 256 attribute names or patterns can be provided to the select
parameter.
If the list contains attribute names that are not prefaced by "-
", only those attributes are included in the response. If the list contains attribute names that are prefaced by "-
", those attributes are excluded from the response.
All attributes that are prefaced by "-
" must follow all attributes that are not prefaced by "-
". In addition, each attribute name in the list must match at least one attribute in the object.
If the list contains both types:
- all attributes that are prefaced by "
-
" must follow all attributes that are not prefaced by "-
" - the difference of the first set of attributes and the second set of attributes is returned in the response
If the list is empty (select=
), all attributes are returned.
In addition:
- The attributes in question are those in the returned
data
,collections
, andlinks
fields only, not themeta
field. - Nesting makes the attribute unique. For example,
select=-abc
does not exclude attributefoo.abc
. - Including or excluding an attribute with nested attributes includes or excludes all the nested attributes. For example,
select=foo
includes bothfoo.abc
andfoo.xyz
. - Wildcard matching is done within an
<attribute-string>
, not an<attribute-name>
. For example,select=*bc
does not include attributefoo.abc
, whereasselect=foo.*bc
does. - The
select
parameter is applied after thewhere
parameter.
Some examples are as follows, where %2A
is the percent URL-encoding for "*
":
; List of all MsgVpn names /SEMP/v2/config/msgVpns?select=msgVpnName ; List of all MsgVpns and their attributes except for their names /SEMP/v2/config/msgVpns?select=-msgVpnName ; Authentication attributes of MsgVpn "finance" /SEMP/v2/config/msgVpns/finance?select=authentication%2A ; All attributes of MsgVpn "finance" except for authentication attributes /SEMP/v2/config/msgVpns/finance?select=-authentication%2A ; Access related attributes of Queue "orderQ" of MsgVpn "finance" /SEMP/v2/config/msgVpns/finance/queues/orderQ?select=owner,permission
Filtering
You can use the where
parameter to specify that a response should include only objects that satisfy certain conditions. When a GET request includes a where
query parameter, the event broker returns only objects whose content matches all the given expressions.
An application can only filter based on fields that would be returned to it for its given URI. For instance, a GET on the /SEMP/v2/config
URI base path cannot filter queues based on the number of currently bound clients—current client bind count is not a configurable attribute of a queue, and not available in that URI base path. However, it could filter based on the configured max-bind-count of the queue.
where
The value of where
is a comma-separated list of expressions. All expressions must be true for the object to be included in the response. Each expression takes the form:
<attribute-name> OP <value>
where:
-
attribute-name
refers to an attribute in the returneddata
field only, not thecollections
,links
ormeta
fields. Wildcards are not allowed inattribute-name
. Write-only attributes are not permitted for use with thewhere
parameter, even if they are opaque and theopaquePassword
query parameter is used. -
OP
is one of "==
", "!=
", "<"
, ">
", "<=
", or ">=
". -
value
may be a number, string,true
, orfalse
, as appropriate for the type ofattribute-name
.
In addition:
-
The "
==
" and "!=
" operators can be used to perform string, numeric, or Boolean (true or false) comparisons. -
The "
<
", ">
", "<=
", and ">=
" operators can be used to perform string or numeric comparisons. -
Where
value
is a string:-
value
may include the "*
" wildcard which can match zero or more characters. The backslash character ("\
") can be used to escape the "*
" wildcard or another backslash. The "*
" wildcard can only be used with the "==
" and "!=
" operators. If "*
" is used as a literal with other operators, it must be escaped using "\"
. -
value
is limited to 266 characters. -
The "
<
", ">
", "<=
", and ">=
" operators perform a simple byte-for-byte comparison.
-
-
Where
value
is a number, it must not exceed the size of the int64 Swagger format type. -
A limit of four expressions may be used at a time.
-
The
where
parameter is applied before theselect
parameter.
Some examples are as follows, where %3D
, %21
, %3E
, and %2A
are the percent URL-encodings for "=
", "!
", ">
", and "*
", respectively:
; Only enabled MsgVpns (enabled==true) /SEMP/v2/config/msgVpns?where=enabled%3D%3Dtrue ; Only MsgVpns using basic non-LDAP authentication (authenticationBasicEnabled==true,authenticationBasicType!=ldap) /SEMP/v2/config/msgVpns?where=authenticationBasicEnabled%3D%3Dtrue,authenticationBasicType%21%3Dldap ; Only MsgVpns that allow more than 100 client connections (maxConnectionCount>100) /SEMP/v2/config/msgVpns?where=maxConnectionCount%3E100 ; Only MsgVpns with msgVpnName starting with "B" (msgVpnName==B*) /SEMP/v2/config/msgVpns?where=msgVpnName%3D%3DB%2A
Retrieving the Number of Objects in a Collection
When you issue a GET request for one of the supported collections, the total number of items is returned in the count
field in the metadata of the GET response.
Counts are supported for the GET method when retrieving the following collections:
-
/SEMP/v2/monitor/msgVpns/<name>/clients
-
clients/*/rxFlows
-
clients/*/transactedSessions
-
clients/*/txFlows
For the
rxFlows
,transactedSessions
, andtxFlows
collections ofclients
, counts are supported only for all clients (that is, the asterisk is mandatory). In this case, only the metadata section is returned in the response. -
-
/SEMP/v2/monitor/msgVpns/<name>/queues
-
queues/<name>/msgs
-
queues/<name>/txFlows
For the
queues
collection and sub-collections, the asterisk is not allowed. -
-
/SEMP/v2/monitor/msgVpns/<name>/topicEndpoints
-
topicEndpoints/<name>/msgs
-
topicEndpoints/<name>/txFlows
For the
topicEndpoints
collection and sub-collections, the asterisk is not allowed. -
-
/SEMP/v2/monitor/msgVpns/<name>/transactions
For the
transactions
collection, the asterisk is not allowed.
If the request includes is filtered by the where
query parameter, the count
field is not included in the response.
For example, suppose the default
Message VPN has the following queues:
-
an exclusive queue
-
a non-exclusive, non-partitioned queue
-
a partitioned queue with four partitions
You could issue the following request:
curl -X GET solace:solace 192.0.2.1:8080/SEMP/v2/monitor/msgVpns/default/queues
The response from the broker would contain the number of queues in the count
field of the meta
section, as shown below. In this case, there are seven total queues (including the partitions) in the Message VPN.
... { ... "meta": { "count": 7, "request": { "method": "GET", "uri": "http://192.0.2.1:8080/SEMP/v2/monitor/msgVpns/default/queues" }, "responseCode": 200 } }
Retrieving Message Counts from Endpoints or Replay Logs
For supported collections, in addition to the number of objects in the collection, the number of contained messages is also returned. The following collections support message counts:
-
/SEMP/v2/monitor/msgVpns/<name>/queues
-
/SEMP/v2/monitor/msgVpns/<name>/topicEndpoints
-
/SEMP/v2/monitor/msgVpns/<name>/replaylogs
Messages are child collections—when you issue a GET request for one of the supported collections, the number (or count) of messages is included in the collections
field of the response.
For example, to retrieve the total number of messages in each queue in the "Sales" Message VPN, you could issue the following request:
curl -u "solace:solace" "192.0.2.1:8080/SEMP/v2/monitor/msgVpns/Sales/queues?count=100&select=queueName,msgs.count"
The collections
section of response from the broker includes a msgs.count
field for each queue, showing the number of messages in that queue. In this case, there are two queues—one queue containing 50 messages and the other containing 75 messages. If there were more queues (up to 100), this response would capture them as well, because the request increased the page size to 100 (the maximum supported).
{ "collections":[ { "msgs":{ "count":50 } }, { "msgs":{ "count":75 } } ], "data":[ { "queueName":"q1" }, { "queueName":"q2" } ], "links":[ {}, {} ], "meta":{ "count":2, "request":{ "method":"GET", "uri":"http://192.0.2.1:8080/SEMP/v2/monitor/msgVpns/Sales/queues?count=100&select=queueName,msgs.count" }, "responseCode":200 } }
Since the queue name is returned in the data
section and the message count is returned in the collections
section, you must use the index of the queue in the data
section to determine the corresponding message count in the collections
section. In the previous example, you can determine that q1
has 50 messages because q1
is the value of the first queueName
field in the data
section and 50 is the value of the first msgs.count
field in the collections
section.
When polling objects (especially queues), it is important to use a select
clause to limit the content of your request to only what you need. For example, if you only want the number of messages in each queue, you should use select=queueName,msgs.count
. Doing so can dramatically reduce the amount of time the broker needs to service the request, and reduce the likelihood of interfering with the performance of other broker services.
Opaque Password
Attributes with the opaque property are also write-only and so cannot normally be retrieved in a GET. However, when a password is provided in the opaquePassword
query parameter, attributes with the opaque property are retrieved in a GET in opaque form, encrypted with this password. The query parameter can also be used on a POST, PATCH, or PUT to set opaque attributes using opaque attribute values retrieved in a GET, so long as:
- the same password that was used to retrieve the opaque attribute values is provided; and
- the broker to which the request is being sent has the same major and minor SEMP version as the broker that produced the opaque attribute values.
The password provided in the query parameter must be a minimum of 8 characters and a maximum of 128 characters.
The query parameter can be used only in the configuration API, and only over HTTPS.
Paging
Paging is supported for the GET method when retrieving collections. A collection might contain hundreds, thousands, or even millions of items. Therefore, these requests must be paged to be manageable. Paging is controlled by two query parameters whose usage is explained below.
Parameter | Meaning |
---|---|
count=<number> |
Include in the response at most this many objects. |
cursor=<opaque value> |
Current position in a paged GET request. |
count
Limits the number of objects in the response.
This can be useful to limit the size of the response for large collections. The minimum value for count
is 1
and the default is 10
. There is also a per-collection maximum value to limit request handling time. Each collection’s actual count
upper bound MAY differ, and requests for count
greater than this upper bound will be capped at the actual upper bound. Because there is no guaranteed way for an application to request all items in a collection in a single GET request, applications should always be written to handle pagination.
The maximum page size varies from collection to collection and will change from version to version. Using a large page size may cause your request to take a long time.
The count
parameter does not guarantee that a minimum number of objects will be returned. A page may contain fewer than count
objects or even be empty. Additional objects may nonetheless be available for retrieval on subsequent pages.
For example:
; Up to 25 MsgVpns /SEMP/v2/config/msgVpns?count=25
cursor
The cursor, or position, for the next page of objects.
Retrieving further pages is controlled by the cursor
query parameter. This parameter provides the event broker with sufficient context to retrieve the next set of objects in the collection.
When a request is made for a collection and there may be additional objects available for retrieval that are not included in the initial response, the response includes a paging
field with two sub-fields:
- The
nextPageUri
provides the URI equivalent of the just-processed request, but with thecursor
andcount
query parameters filled in to GET the next set of objects from the collection. - The
cursorQuery
string provides only thecursor
value to use in the next request. This is useful for clients built using generated SDK libraries, which do not directly operate on URIs.
Applications must continue to use the cursorQuery
if one is provided in order to retrieve the full set of objects associated with the request, even if a page contains fewer than the requested number of objects (see the count
query parameter documentation) or is empty.
Cursors are opaque data that should not be created or interpreted by SEMP clients, and should only be used as described.
The absence of the paging
field in a response indicates that either the full collection has been returned or that you have retrieved the last page of a collection.
In SEMP, while retrieving a collection, it is possible to receive a partially-filled or even empty page in the midst of the paged response. This is particularly common when object filtering is used. Applications working with paging should continue to retrieve the next page until the paging
field is absent in the response to confirm they have retrieved the full response.
Rate Limiting
Currently, SEMP does not enforce a rate limit. It is recommended that users avoid aggressively polling the event broker. In general, the average number of SEMP requests made to an event broker should be less than 10 requests/sec.
Transactions
SEMP does not support transactions because it is not possible to group together multiple SEMP requests and guarantee their success or failure as a complete unit.
However, any individual SEMP POST, PUT, or PATCH request will complete successfully or not at all. For example, a PATCH to a queue, changing three attributes, where the change to the third attribute fails will leave the queue without the first two attributes changed; all three changes must succeed, otherwise the object will be left in its original state. However, this support is still not transactional in that an event broker restart midway through the handling of an individual request may result in the request only being partially satisfied. Concurrent modifications of Solace objects by CLI or legacy SEMP users is another way that a request may fail and leave a request partially satisfied. SEMP v2 users should avoid concurrent modification of objects by CLI or legacy SEMP users.
Any individual SEMP GET request which returns multiple objects, is guaranteed to complete successfully or not at all. For instance, when doing a GET of a collection, partial collection results will not be returned if there is a failure while processing the GET. Similarly, a GET of an individual object returns all the state of that object, or none.
Sorting
Sorting of query responses is not supported.