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:

Characters that are allowed in a URI but do not have a reserved purpose are called unreserved.  These include uppercase and lowercase letters, decimal digits, hyphen, period, underscore, and tilde.
      unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"

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.