The HTTP binding for OpenMessaging consists of two parts: producing and consuming. We use HTTP2 in the implemention.
The main idea of producing part of http binding is simple, we just map all the essential info into the http protocal.
We use POST method to send messages.
All the meta info of message is in the HTTP header, and message body is put in the HTTP body.
| Header | Constraints | Demo | Description |
|---|---|---|---|
| x-oms-version | Required | 1.0.0 | version of OMS |
| x-oms-h-destination | Required | orderQueue | See message model for details. |
| x-oms-h-messageId | Required | 7F00000100002873000000000004F49C | See message model for details. |
| x-oms-h-bornTimestamp | Required | 1533780827824 | See message model for details. |
| x-oms-h-bornHost | Required | 172.24.0.101:10035 | See message model for details. |
| x-oms-h-storeTimestamp | Required | 1533780827825 | See message model for details. |
| x-oms-h-storeHost | Required | 172.24.0.102:52511 | See message model for details. |
| x-oms-h-expireTime | OPTIONAL | 1533780830000 | See message model for details. |
| x-oms-h-priority | OPTIONAL | 1 | See message model for details. |
| x-oms-h-compression | OPTIONAL | gzip | See message model for details. |
| x-oms-h-traceId | OPTIONAL | 1E0578887D3F18B4AAC22B64D2B00A5E | See message model for details. |
| x-oms-h-transactionId | OPTIONAL | 1E0578887D3F18B4AAC22B64D2B40A62 | See message model for details. |
| x-oms-h-messageKey | OPTIONAL | orderId-103368921567 | See message model for details. |
| x-oms-h-delayTime | OPTIONAL | 30000 | See message model for details. |
| x-oms-h-durability | OPTIONAL | 1 | See message model for details. |
| x-oms-h-correlationId | OPTIONAL | 7F00000100002873000000000004F2B4 | See message model for details. |
| x-oms-p-service | OPTIONAL | helloService | All properties start with x-oms-p- |
| status code | Description |
|---|---|
| 200 | Success |
| 4xx or 5xx | Failed. Detailed error code or failure reason is decided by the underlying vendor |
vendors can add some specail meta info in the response header, e.g. message offset for this offset.
Response body is not required.
In pull mode, the consumer get message in the request and response mode. At most one message would be returned for one pull request. Useful for testing and low qps consuming scenario.
| http header | Constraints | Description |
|---|---|---|
| x-oms-version | Required | version of OMS |
| x-oms-consumerId | Required | user defined client Id. (e.g. consumer group in RocketMQ/Kafka) |
| x-oms-source | Required | consume message from this queue or topic. See x-oms-h-destination in producer. |
| x-oms-ack | OPTIONAL | If set true, ack is required for the at least once delivery semantics. False is default value for at most once delivery semantics |
| x-oms-waitMills | OPTIONAL | Time in milliseconds for waiting message. Used in long polling. |
| status code | Description |
|---|---|
| 200 | Success, with message |
| 204 | Success, no new message |
| 4xx or 5xx | Failed. Detailed error code or failure reason is decided by the underlying vendor |
Message formated in HTTP protocal, same as produce format.
The main difference between pull and push mode is that, in push mode, you can get multi messages with one request.
| http header | Constraints | Description |
|---|---|---|
| x-oms-version | Required | version of OMS |
| x-oms-consumerId | Required | user defined client Id. (e.g. consumer group in RocketMQ/Kafka) |
| x-oms-source | Required | consume message from this queue or topic. See x-oms-h-destination in producer. |
| x-oms-ack | OPTIONAL | If set true, ack is required for the at least once delivery semantics. False is default value for at most once delivery semantics |
| x-oms-waitMills | OPTIONAL | Time in milliseconds for waiting message. Used in long polling. |
| x-oms-callbackURL | OPTIONAL | Enable callback push mode, server will post messages to this URL. If empty url is set, previous callback procedure will be stopped. |
| status code | Description |
|---|---|
| 200 | Success. |
| 4xx or 5xx | Failed. Detailed error code or failure reason is decided by the underlying vendor |