SEMP Features

This section provides more details about the SEMP v2 features discussed in SEMP API Architecture:

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, and links fields only, not the meta field.
  • Nesting makes the attribute unique. For example, select=-abc does not exclude attribute example.abc.
  • Including or excluding an attribute with nested attributes includes or excludes all the nested attributes. For example, select=example includes both example.abc and example.xyz.
  • Wildcard matching is done within an <attribute-string>, not an <attribute-name>. For example, select=*bc does not include attribute example.abc, whereas select=example.*bc does.
  • The select parameter is applied after the where 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 returned data field only, not the collections, links or meta fields. Wildcards are not allowed in attribute-name. Write-only attributes are not permitted for use with the where parameter, even if they are opaque and the opaquePassword query parameter is used.

  • OP is one of "==", "!=", "<", ">", "<=", or ">=".

  • value may be a number, string, true, or false, as appropriate for the type of attribute-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 the select 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, and txFlows collections of clients, 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 finance 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/finance/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/finance/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, by a user with an access-level of global/admin, 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 the cursor and count query parameters filled in to GET the next set of objects from the collection.
  • The cursorQuery string provides only the cursor 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 Solace 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 Solace 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.