SEMP API Architecture

SEMP v2 is composed of three separate APIs that each serve a different purpose.

API	Base Path	Purpose
Configuration	`/SEMP/v2/config`	Reading and writing configuration state.
Monitoring	`/SEMP/v2/monitor`	Querying administrative and operational state.
Action	`/SEMP/v2/action`	Performing actions.

The sections that follow describe the structure of the SEMP API in more detail. These sections include:

Reserved Characters
SEMP Resources
Query Parameters
Collection Counts
HTTP Methods
HTTP Status Codes
HTTP Content

Reserved Characters

The following are considered "data" within a SEMPv2 URL:

the identifying attributes of a resource; and
the values of query parameters.

When these data portions of the URL contain characters outside the RFC 3986 "unreserved" character set (A-Z, a-z, 0-9, -, _, ., and ~), then these characters must be percent-encoded.

However, when commas are used as delimiters for a resource with multiple identifying attributes or for a query parameter with multiple values, they must not be percent-encoded.

SEMP Resources

SEMP v2 uses URIs to address manageable resources of the PubSub+ event broker. Resources are individual objects, collections of objects, or (exclusively in the Action API) actions.

Resources are always nouns, with individual objects being singular and collections being plural. Objects within a collection are identified by an object ID (obj-id), which follows the collection name with the form collection-name/obj-id. An obj-id consists of one or more identifying attributes, separated by commas. Commas that appear in the identifying attribute itself must be percent-encoded.

Objects are composed of attributes, actions, collections, and other objects, which are in turn described by JSON objects as name/value pairs. The collections and actions of an object are not contained directly in the object's JSON content; rather the content includes an attribute containing a URI which points to the collections and actions. These contained resources must be managed through this URI.

At a minimum, every object has a uri attribute containing the URI pointing to itself. Objects in collections also have at least one identifying attribute. These attributes can have properties—see Attribute Properties below for details.

Collections are unordered lists of objects (unless described as otherwise), and are described by JSON arrays. Each item in the array represents an object in the same manner as the individual object would normally be represented.

Actions within an object are identified by an action-id, which follows the object name with the form obj-id/action-id.

Actions are also composed of attributes, and are described by JSON objects as name/value pairs. Unlike objects, however, they are not members of a collection and cannot be retrieved, only performed. Actions only exist in the action API.

Some examples are as follows:

/SEMP/v2/config/msgVpns                        ; MsgVpn collection
/SEMP/v2/config/msgVpns/a                      ; MsgVpn object named "a"
/SEMP/v2/config/msgVpns/a/queues               ; Queue collection in MsgVpn "a"
/SEMP/v2/config/msgVpns/a/queues/b             ; Queue object named "b" in MsgVpn "a"

/SEMP/v2/config/msgVpns/a/bridges              ; Bridge collection in MsgVpn "a"
/SEMP/v2/config/msgVpns/a/bridges/b,auto       ; Bridge object named "b" with virtual router "auto" in MsgVpn "a"

/SEMP/v2/action/msgVpns/a/queues/b/startReplay ; Action that starts a replay on Queue "b" in MsgVpn "a"

/SEMP/v2/monitor/msgVpns/a/clients             ; Client collection in MsgVpn "a"
/SEMP/v2/monitor/msgVpns/a/clients/c           ; Client object named "c" in MsgVpn "a"

These examples illustrate cases where the object ID of the resource is composed of a single part (commonly a name). Some objects in the event broker are uniquely identified by more than one string, in which case you concatenate the strings together with the "," (comma) character to form the object's ID. For example:

/SEMP/v2/config/msgVpns/finance/bridges/ny-to-ldn,primary

In the example above, there is a collection of bridges within the finance Message VPN, one of which is called ny-to-ldn belonging to the primary virtual-router.

As a general rule, resource paths in the SEMP API are composable. That is, the client application, by following well understood patterns, can build the URI itself. In particular, SEMP does not make use of obfuscated or generated UUIDs or any other scheme for generating unique URIs for each resource. The SEMP API Reference shows the resource URI for each event broker configuration resource.

Attribute Properties

Attributes in an object or action may have any combination of the following properties:

Property	Meaning
Identifying	The attribute is involved in unique identification of the object, and appears in its URI.
Const	The attribute value can be chosen only during object creation.
Required	The attribute must be provided in the request.
Read-Only	The attribute value cannot be changed. Read-only attributes may appear in POST and PUT/PATCH requests. However, if a read-only attribute is not marked as identifying, it will be ignored.
Write-Only	The attribute can only be written, not read. This attribute will not be returned in GET requests. Opaque attributes can be retrieved in opaque form even if they are write-only.
Requires-Disable	The attribute cannot be changed while the object (or the relevant part of the object) is administratively enabled.
Auto-Disable	Modifying this attribute while the object (or the relevant part of the object) is administratively enabled causes the event broker to temporarily disable one or more attributes to apply the change. This action may be service impacting.
Deprecated	The attribute is deprecated and may be eliminated in a subsequent SEMP version.
Opaque	The attribute can be set or retrieved in opaque form when the `opaquePassword` query parameter is present. See Opaque Password for details.

In some requests, certain attributes may only be provided in certain combinations with other attributes:

Relationship Meaning

Relationship	Meaning
Requires	The attribute may only be changed by a request if a particular attribute or combination of attributes is also provided in the request. The `requires` property will not be enforced for an attribute when all of the following conditions are met: the attribute is not write-only; the value provided for the attribute is the same as its current (or, on object creation, its default) value; and the attribute requires a write-only attribute. In addition, the `requires` property may not be enforced even if only conditions (a) and (b) are met.
Conflicts	The attribute may only be provided in a request if a particular attribute or combination of attributes is not also provided in the request.

Requires

The attribute may only be changed by a request if a particular attribute or combination of attributes is also provided in the request.

The requires property will not be enforced for an attribute when all of the following conditions are met:

the attribute is not write-only;
the value provided for the attribute is the same as its current (or, on object creation, its default) value; and
the attribute requires a write-only attribute.

In addition, the requires property may not be enforced even if only conditions (a) and (b) are met.

Conflicts

The attribute may only be provided in a request if a particular attribute or combination of attributes is not also provided in the request.

In the monitoring API, any non-identifying attribute may not be returned in a GET.

The SEMP API Reference identifies all attribute properties for each resource so that it is clear which attributes of an object have assigned properties.

HTTP Methods

The HTTP methods of POST, PUT, PATCH, DELETE, and GET manipulate resources according to the following general principles. Note that some methods are only used in certain APIs:

Method	Resource	Description	Request Body	Response Body	Notes
POST	Collection	Creates a new object	Initial attribute values	Object attributes and metadata	Absent attributes are set to default. If the object already exists, the event broker returns a 400 error.
PUT	Object	Updates an existing object	New attribute values	Object attributes and metadata	If the object does not exist, the event broker creates it. Absent attributes are set to default, except if the SEMP user is not authorized to modify the attribute. In this case, its value is left unchanged rather than set to default. In addition, the values of write-only attributes are not set to their defaults on a PUT, except in the following two cases: there is a mutual required relationship with another non-write-only attribute, both attributes are absent from the request, and the non-write-only attribute is not currently set to its default value; or the attribute is also opaque and the `opaquePassword` query parameter is provided in the request. For example, because REST consumer credentials are write-only attributes that have a mutual required relationship with other non-write-only attributes, any update to a REST consumer using these attributes must provide them with every PUT request or they will be removed (set to a default value of `""`).
PUT	Action	Performs an action	Action arguments	Action metadata
PATCH	Object	Updates an existing object	New attribute values	Object attributes and metadata	Absent attributes are left unchanged. If the object does not exist, the event broker returns a 400 error.
DELETE	Object	Destroys an existing object	Empty	Object metadata	If the object does not exist, the event broker returns a 400 error.
GET	Object	Retrieves an object	Empty	Object attributes and metadata	If the object does not exist, the event broker returns a 400 error.
GET	Collection	Retrieves a collection of objects	Empty	Object attributes and collection metadata	If the collection is empty, the event broker returns the empty collection with a 200 code.

Method Override

If you're using a client that doesn't support all of the HTTP methods, or you're passing requests through a proxy that limits HTTP methods, you can override the HTTP method by using a POST and setting the X-Http-Method-Override header to the desired method. For instance, to do a PATCH request, do a POST with header X-Http-Method-Override: PATCH.

Query Parameters

Query parameters are used with all HTTP methods for various purposes.

Multiple query parameters can be used together in a single URI, separated by the ampersand character. For example:

; Request for the MsgVpns collection using two hypothetical query parameters
; "q1" and "q2" with values "val1" and "val2" respectively
/SEMP/v2/config/msgVpns?q1=val1&q2=val2

The API reference lists the query parameters for each endpoint.

Common Query Parameters

There are a handful of query parameters that are common to many URIs because they allow for advanced manipulation of query results such as filtering and pagination. These parameters are listed in the following table.

Parameter	Meaning	Applies To		For Details, See...
Parameter	Meaning	Object	Collection	For Details, See...
select=list-of-attrs	Include in the response or exclude from the response the specified data attributes.			Returning Selected Data Fields
where=list-of-exprs	Include in response objects where all listed expressions are true.			Filtering
cursor=opaque-value	The current position in a paged GET request.			Paging
count=number	Include at most this many objects in the response.			Paging
opaquePassword=password	Provides a mechanism to return write-only attributes in the response.			Opaque Password

Collection Counts

Counts are supported for only certain collections. For details, see Retrieving the Number of Objects in a Collection.

HTTP Status Codes

The API returns an HTTP status code in each response. These codes represent three families of responses: success (2xx), client error (4xx), and server error (5xx).

Code	Status	Meaning
200	OK	The request was successful.
204	No Content	The event broker successfully processed the request, and is not returning any content.
400	Bad Request	Something is wrong with the request. For example, there is a typo or the requested object cannot be found.
401	Unauthorized	Something is wrong with the client authentication. For example, the password is incorrect or the user does not exist.
403	Forbidden	The request contained valid data and was understood by the event broker, but it is refusing action.
404	Not Found	The requested resource could not be found, but may be available in the future.
414	URI Too Long	The URI provided was too long for the event broker to process.
500	Internal Server Error	Something went wrong on the event broker.
502	Bad Gateway	The event broker was acting as a gateway or proxy and received an invalid response from the upstream server.
503	Service Unavailable	The event broker cannot handle the request (because it is overloaded or down for maintenance).
504	Gateway Timeout	The event broker was acting as a gateway or proxy and did not receive a timely response from the upstream server.
529	No SEMP Session Available	The event broker cannot create the requested session because there are too many SEMP clients or Broker Manager users connected.

500-level errors indicate that there is a problem with the event broker, such as a system overload, that is preventing the request from completing successfully. On the other hand, 400-level errors may be something that the client can correct and retry. A 401 error is returned on API authentication failures for compatibility with some applications (such as Web browsers) that use this HTTP status code to prompt clients to authenticate.

In the case of errors, the body of the HTTP response contains more detailed information about the nature of the error and contains additional information about the request. This is described in SEMP Error Handling.

HTTP Content

SEMP uses JSON to encode the payload for requests and responses.

You can include a Content-Encoding header with the value of gzip to compress requests. Similarly, specify an Accept-Encoding header of gzip to ask the event broker to compress its responses.

A Content-Type header value of application/json is required for requests with bodies.

The format for the requests and responses is URI-dependent and fully documented in the SEMP API Reference.

One of the goals for object payloads is to enable the get, update, modify usage pattern (where you GET an object, make some change to it, and then PUT the object to save the change). SEMP is designed with this type of use in mind, meaning, for example:

The API harmonizes the format for objects between the GET, POST, PUT, and PATCH methods.
The PUT and PATCH methods ignore non-identifying read-only attributes in HTTP content objects.
The schemas for objects returned on a GET contain write-only attributes, like password, because they are needed for creating objects. However, these attributes are absent from the actual responses.

Currently, SEMP only supports UTF-8 encoding for HTTP content.

Responses

All SEMP requests have a non-empty response. All responses are divided into two sections: data (what was requested) and metadata (information about the response). If the corresponding request contains an Accept-Encoding header allowing for compression, the event broker compresses the response body appropriately.

The basic JSON structure of a SEMP response is as follows:

{
  "collections": [
    {
      "<collection-name>": {
        "count": <number>
      },
      "<collection-name>": {
        "count": <number>
      }
    }
  ],
  "data": {
    // data attributes
  },
  "links": {
    // links to XXXX
  },
  "meta": {
    "count": <number>,
    "error": {
      "code": <number>,
      "description": <string>,
      "status": <string>
    },
    "paging": {
      "cursorQuery": <string>
      "nextPageUri": <string>
    },
    "request": {
      "method": <string>,
      "uri": <string>
    },
    "responseCode": <number>
  }
}

Collections Field

If a GET is performed on a supported collection, the count of the objects in its child collections is returned in the collections section. For details, see Retrieving Message Counts from Endpoints or Replay Logs.

Data Field

The data field is optional. If present, its value is a JSON object or array. The content returned in this field is URI dependent.

Links Field

The links field is optional. As described in SEMP Resources, above, objects are composed of attributes, actions, collections, and other objects. If present in the response, the links field contains the list of URIs that point to the collections and actions. You must use these URIs to manage the contained resources.

Meta Field

The meta field is mandatory. Its value is a JSON object, and it has a common definition across all URIs. The following table summarizes the information in the meta field.

Field	Sub-Field	Description	Optional?
`count`		The total number of objects requested, irrespective of page size. This may be a count of all objects in a collection or a filtered subset. It represents a snapshot in time and may change when paging through results.	Yes
`responseCode`		The HTTP status code, one of 200 (success), 4xx (client error), or 5xx (server error).	No
`request`	`method`	The HTTP method of the request which resulted in this response.	No
`request`	`uri`	The URI of the request which resulted in this response. The URI may be normalized.	No
`error`	`code`	The error code which uniquely identifies the error that has occurred.	Yes–only provided on errors.
	`description`	The verbose description of the problem.
	`status`	The terse status string associated with `code`.
`paging`	`cursorQuery`	The cursor, or position, for the next page of objects. Use this as the `cursor` query parameter of the next request.	Yes–only provided if there are more pages in a collection.
`paging`	`nextPageUri`	The URI of the next page of objects. The `cursorQuery` field is already embedded within this URI.	Yes–only provided if there are more pages in a collection.

Provide feedback