SEMP API Protocol Design

This section provides developers with important HTTP wireline information for the SEMP API.

URI Structure

The SEMP API uses URIs to address event broker resources. Following a conventional REST approach, URIs can be decomposed into the following parts:

URI = scheme:[//authority path[?query][#fragment]

• Scheme—The API supports both http and https schemes.
• Authority—Identifies user, host and port in the normal ways. The host and port refer to the SEMP management interface of the event broker.
• Path—Represents the address of an event broker resource. This is explained further in SEMP Resources.
• Query—Used to control behaviors like filtering and paging in various methods. This is explained further below in Query Parameters.
• Fragment—Not used by the API.

Reserved Characters

Event broker configuration objects can use characters in their names that are reserved in URIs. When this occurs, these characters must be encoded following the URI percent encoding guidelines. RFC-3986 – URI Generic Syntax and outlined unreserved and reserved characters. All reserved characters must be encoded using percent encoding. It is recommended that you encode all characters outside of the unreserved character set for event broker configuration object identifying attributes. The URI unreserved character set is:

The only exception to this rule is the comma when used in the URI of resources. Currently, any comma in the resource identifier must not be escaped. It is expected that this limitation will be removed in a future version of the SEMP API.

Query Parameters

Query parameters are used with all HTTP methods for various purposes. While individual URIs support other specific parameters, the following are common to many URIs.

For details outlining the use of query parameters in paging and filtering see Paging.

Query Parameters

Parameter	Meaning	Applies To
		Object	Collection
select=list-of-attrs	Include in the response or exclude from the response the selected data attributes.	x	x
where=list-of-exprs	Include in response objects where all listed expressions are true.		x
cursor=list-of-exprs	Current position in a paged GET request.		x
count=number	Include at most this many objects in the response.		x

HTTP Methods

The HTTP methods of POST, PUT, PATCH, DELETE, and GET manipulate resources according to the following general principles:

Method	Resource	Description	Missing Request Attributes
POST	Collection	Creates a new object	Set to default
PUT	Object	Updates an existing object	Set to default. (See note in role-based access control Role-Based Access Control).
PATCH	Object	Updates an existing object	Left unchanged
DELETE	Object	Destroys an existing object	N/A
GET	Collection	Retrieves a list of matching objects	N/A
GET	Object	Retrieves an object	N/A

Method Override

When using a client that does not support all of the HTTP methods, or if passing 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.

HTTP Response Codes

The API uses four distinct HTTP response codes. These represent three families of responses: success, client error, and server error.

Code	Meaning
200	OK: the request was successful
400	FAIL: something is wrong with the request
401	FAIL: something is wrong with the client authentication
500	FAIL: something went wrong on the event broker

In general, 500-level errors are not worth retrying. There is an issue with the event broker preventing the request from completing successfully. For example, this could be system overload or other reasons. 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 response 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 Headers

Use of HTTP headers is generally not required by SEMP outside the needs of the HTTP protocol. The following table summarizes the SEMP HTTP header usage.

Type	Header	Value	Meaning
Request	Authorization	username/password, Bearer token	Basic or OAuth authentication credentials.
	User-Agent	varies	Identifies originating agent, for debugging.
	Accept-Encoding	gzip	Client is willing to accept encoded response (for example, compressed).
	X-HTTP-Method-Override	PUT, PATCH, DELETE	Used to override a POST or GET method as another method to work around restrictions of various clients and proxies. See Method Override
Both	Content-Length	number	The size of the request/response body.
	Content-Type	application/json	Content-type of request/response body.
	Content-Encoding	gzip	Content is encoded (for example, compressed).
Response	Cache-Control	no-cache	Disable caching in client.
	Server	Solace	Indicates you are interacting with an event broker.
	Date	The date	The time and date of the response.

HTTP Content

SEMP uses JSON to encode the payload for requests and responses. Payloads may be compressed using gzip. When using gzip compression, the Content-Encoding header field must be provided indicating this.

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. 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.
• PUT and PATCH methods will ignore non-identifying read-only attributes in HTTP content objects.
• The schema for objects returned on a GET will contain write-only attributes, like password, as these are used during object creation, but these attributes are absent from responses.

Currently, SEMP only support 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). The event broker always provides response bodies which have been “pretty-printed” (that is, with white space, indentation, etc.). If the corresponding request contained an Accept-Encoding header allowing for compression, the event broker MUST compress the response body appropriately.

The basic JSON structure of this response is:

{
  "data": {
    // data attributes, as per previous examples
  },
  "meta": {
    "error": {
      "code": <number>,
      "description": <string>,
      "status": <string>
    },
    “paging”: {
      “cursorQuery”: <string>
      “cursorUri”: <string>
    }
    "request": {
      "method": <string>,
      "uri": <string>
    },
    "responseCode": <number>
  }
}

Data field

The data field is optional. If present, its value is a JSON object or array. The content of the object or collection is URI dependent.

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 meta information.

Field	Sub-Field	Description	Optional?
responseCode		HTTP Response Code (200, 400, 401, 500).	No
request	method	The method of the request which generated this response.	No
	uri	The URI of the request which generated this response.
error	code	Solace error code. For conditional execution by the client.	Yes–only provided on errors.
	description	Solace free-form description of the error, intended for human consumption.
	status	Solace error status string for logging and debugging use.
paging	cursorQuery	The “cursor” query parameter string.	Yes–only provided if there are more pages in a collection.
	cursorUri	The “cursor” URI.