API
Produce Service
The produce service can be used to produce individual messages to a stream. The Rest Proxy supports multiple datatypes for key and value. Producing custom headers is not supported.
Lifecycle
For every produce call the REST Proxy unloads the SSL context and runs the ACL checks against the stream on which the produce is made.
If access is granted, a producer will be created internally and cached using the AXUAL-PRODUCER-UUID provided in the HTTP Headers.
The rest of the provided http headers are used to initialize the producer which then will be reused in subsequent calls (given the same AXUAL-PRODUCER-UUID).
That producer object remains cached for a period of time that is dictated by a REST Proxy configuration parameter (namely axual.producer.cache-ttl-ms), which defaults to 6 minutes.
Producer objects are evicted from the cache after axual.producer.cache-ttl-ms of inactivity.
API Specification Produce Service
HTTP Request Structure
End Point |
<baseurl>/stream/{environment}/{stream} |
HTTP Method |
|
Content-Type |
|
Path Variables
Path Variable |
Description |
|
The environment |
|
The stream name as specified in the Self Service definition |
HTTP Headers
Header Name |
Require / Optional |
Description |
|
Required |
The unique consumer instance id used to identify the consumer object for the session |
|
Required |
The application id of the the producer application as specified in the Self Service |
|
Optional |
The version of the the producer application |
|
Optional |
The acknowledgement waiting strategy to be used, NONE doesn’t wait, SINGLE waits for the target acknowledgement, ALL waits for the replication acknowledgement. |
|
Optional |
The strategy for ordering, KEEPING will ensure delivery or the message in order. With LOSING messages can overtake other messages. |
|
Optional |
How long does the call wait for delivery in milliseconds. Valid Range 50 - 60000. |
|
Optional |
How long does sending engine wait for extra messages in the batch. Valid range 0-2000. |
| The UUID needs to be unique (guaranteed by using a UUID generator), generated prior to the producer loop. This way the producer object created internally is unique to the produce session |
HTTP Responses Structure
Avro Schema Service
Streams can use Avro schema definitions for keys and/or values. These schemas need to be provided with every produce call. This will usually result in a relatively high overhead in data. The schemas are stored in the backend and ids are provided for these schemas. The produce call also accepts these ids. The Avro service can provide the id of a specified schema for a specific stream and environment.
API Specification Avro Schema Service
HTTP Request Structure
Endpoint |
<baseurl>/schema/{environment}/{stream} |
HTTP Method |
|
Path Variables
Path Variable |
Description |
|
The environment |
|
The stream name as specified in the Self Service definition |
HTTP Responses Structure
Consume Service
The consume service can be used to consume messages from a stream. The Rest Proxy supports multiple datatypes for key and value. Headers are returned as name and list of not supported.
Lifecycle
For every consume call the REST Proxy unloads the SSL context and runs the ACL checks against the stream on which the consume is made.
If access is granted, a consumer will be created internally and cached using the AXUAL-CONSUMER-UUID provided in the HTTP Headers.
The rest of the provided http headers are used to initialize the consumer which then will be reused in subsequent calls (given the same AXUAL-CONSUMER-UUID).
That consumer object remains cached for a period of time that is dictated by a REST Proxy configuration parameter (namely axual.consumer.cache-ttl-ms), which defaults to 6 minutes.
Consumer objects are evicted from the cache after axual.consumer.cache-ttl-ms of inactivity.
API Specification Consume Service
HTTP Request Structure
End Point |
<baseurl>/stream/{environment}/{stream} |
HTTP Method |
|
Content-Type |
|
Path Variables
Path Variable |
Description |
|
The environment |
|
The stream name as specified in the Self Service definition |
HTTP Headers
Header Name |
Require / Optional |
Description |
|
Required |
The unique consumer instance id used to identify the consumer object for the session |
|
Required |
The application id of the the consumer application as specified in the Self Service |
|
Required |
Contains the type of the key data, this should match with the data used in the stream. Can be |
|
Required |
Contains the type of the value data, this should match with the data used in the stream. Can be |
|
Required |
This controls the offset should be committed on next consume call or immediately after the read for the current consume call. Valid values are |
|
Optional |
The version of the the consumer application |
|
Optional |
The maximum number of messages to be returned for the call. |
|
Optional |
This controls if the stream should be read from the begin (EARLIEST) or the end(LATEST) if no offset has been found. |
|
Optional |
The amount of time to wait for the backend poll to complete. During creation of the backend consumer or rebalance this might result in an empty response. This delay during creation/rebalance should normally not take more than 10 seconds. |
|
Optional |
Return consumer assigned partition offsets in response. Valid values are TRUE and FALSE. |
| The UUID needs to be unique (guaranteed by using a UUID generator) and generated prior to the consumer loop. This way the consumer object created internally is unique to the consume session. |