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 “ |
Yes–only provided if there are more pages in a collection. |
cursorUri |
The “cursor” URI. |