-
Notifications
You must be signed in to change notification settings - Fork 7
6. HTTP API
The HTTP server, IIS HTTP module, and OWIN middleware provide REST APIs that support HTTP transport and subscriptions.
The message resource is used to send a message to the Platibus instance.
POST requests cause a new message to be created.
No query parameters are required or supported.
The following headers are expected in POST requests to the message resource:
| Header | Use | Constraints | Description |
|---|---|---|---|
| Platibus-MessageId | Recommended | GUID | An ID that uniquely identifies the message |
| Platibus-MessageName | Required | String | A discriminator value used to select handling rules and/or identify appropriate .NET types for deserializing message content |
| Platibus-Origination | Required | URI | The base URI of the sender |
| Platibus-Destination | Optional | URI | The URI of the recipient |
| Platibus-ReplyTo | Optional | URI | The URI of the instance to which replies to this message should be addressed |
| Platibus-RelatedTo | Optional | GUID | The ID of the message to which this message is a reply |
| Platibus-Topic | Optional | String | The name of the topic to which this message was published |
| Platibus-Sent | Recommended | ISO 8601 Date/Time | The UTC timestamp indicating when the message was sent |
| Platibus-Published | Recommended | ISO 8601 Date/Time | The UTC timestamp indicating when the message was published |
| Platibus-Importance | Optional | Integer | The importance of this message, which determines queueing and congestion behavior (-1 = Low; 0 = Normal; 1 = High; 2 = Critical) |
| Platibus-Expires | Optional | ISO 8601 Date/Time | The UTC timestamp at which the message expires and should be discarded without processing |
| Content-Type | Required | String | The MIME type/encoding of the request content |
The body should contain the message serialized and encoded per the specified Content-Type.
The response will have empty content with one of the following HTTP status codes:
| Status | Reason Phrase | Meaning |
|---|---|---|
| 202 | Accepted | The message has been received and will be handled |
| 401 | Unauthorized | The sender is not authorized to send messages to this instance |
| 422 | Unprocessable Entity | Message headers indicated that message should be processed immediately but the message was not acknowledged. No handling rules were found for the specified message name; all handlers returned without acknowledging the message; or all handlers terminated abnormally |
| 500 | Internal Server Error | Unknown/unhandled error processing the message |
The topic resource lists available topics and allows callers to manipulate subscriptions.
Return the list of topics declared in this instance.
No query parameters are required or supported.
The response Content-Type is application/json and consists of a JSON serialized array of topic names:
["Topic1", "Topic2"]The subscription resource for a topic instance supports creating, updating (renewing), or deleting subscriptions to a particular topic.
Post requests are used to create or update (renew) subscriptions to a topic.
Content specified in the request is ignored.
The following query parameters are expected:
| Parameter | Use | Constraints | Description |
|---|---|---|---|
| uri | Required | URI | The base URI of the subscriber |
| ttl | Optional | int | The Time To Live (TTL) for the subscription in seconds |
If the ttl parameter is omitted then the subscription will not expire.
The response will have empty content with one of the following HTTP status codes:
| Status | Reason Phrase | Meaning |
|---|---|---|
| 200 | OK | The subscription was created or updated successfully |
| 202 | Accepted | The request was valid and the subscription will be created or updated |
| 400 | Bad Request | The 'uri' query parameter was not specified |
| 404 | Not Found | The specified {topic} is not declared on this instance |
| 401 | Unauthorized | The sender is not authorized to create subscriptions |
| 500 | Internal Server Error | Unknown/unhandled error processing the message |
Removes a subscription to a topic.
The following query parameters are expected:
| Parameter | Use | Constraints | Description |
|---|---|---|---|
| uri | Required | URI | The base URI of the subscriber |
The response will have empty content with one of the following HTTP status codes:
| Status | Reason Phrase | Meaning |
|---|---|---|
| 200 | OK | The subscription was deleted successfully |
| 400 | Bad Request | The 'uri' query parameter was not specified |
| 404 | Not Found | The specified {topic} is not declared on this instance |
| 401 | Unauthorized | The sender is not authorized to create subscriptions |
| 500 | Internal Server Error | Unknown/unhandled error processing the message |
Returns journaled messages
The following query parameters are expected:
| Parameter | Use | Constraints | Description |
|---|---|---|---|
| category | Optional | String | Filters results to include only messages with the specified journal category, e.g. Sent, Published, or Received
|
| topic | Optional | String | Filters results to include only messages published to the specified topic |
| messageName | Optional | String | Filters results to include only messages with message names containing the specified substring |
| from | Optional | ISO 8601 Date/Time | Filters results to include only messages sent, received, or published on or after the specified timestamp (e.g. 2017-10-17T00:00:00) |
| to | Optional | ISO 8601 Date/Time | Filters results to include only messages sent, received, or published before specified timestamp (e.g. 2017-10-17T00:00:00) |
| start | Optional | Integer | The zero-based index of the first journaled message to return. Default is 0. |
| count | Required | Integer | The number of journaled messages to return |
The response will have one of the following HTTP status codes:
| Status | Reason Phrase | Meaning |
|---|---|---|
| 200 | OK | The request was valid and results are contained in the response vontent |
| 400 | Bad Request | The 'count' query parameter was not specified or one of the other request parameter values was not valid |
| 500 | Internal Server Error | Unknown/unhandled error processing the request |
The content type of the response is application/json and has the following structure:
{
"errors": [],
"start": "0",
"next": "0",
"endOfJournal": true,
"entries": [
{
"pos": "0",
"ts": "2017-10-18T09:15:12.4428627Z",
"category": "Sent",
"data": {
"headers": {
"Platibus-MessageId": "d8de3a3d-7394-43ff-b00b-cdc62697ff87",
"Platibus-MessageName": "Test",
"Platibus-Origination": "http://localhost:80/platibus/",
"Platibus-Destination": "http://localhost:81/platibus/",
"Platibus-Sent": "2017-10-18T09:15:12.4428627Z",
"Content-Type": "text/plain"
},
"content": "Hello, World!"
}
}
]
}