The Ingest REST API is a service that receives data and passes it to Kafka to stream to a target. Currently, Ingest is the only way to stream data into Listener.
Base URL
The Ingest REST API has its own hostname, which varies across Listener installations. The administrator can customize the hostname when installing Listener as follows:
https://listener-ingest-services.YOURCOMPANY.DOMAIN/v1/
Versioning
We recommend using /v1/ in the path to denote the specific API version. If you do not use the version path, it defaults to the most recent version. Using a specific version prevents errors in your applications due to API updates.
Authorization
To publish data, a source must be registered with Listener through the Ingest REST API (REST) or application interface (MQTT). When using a REST source, it generates an API key to use in requests to send data to the Ingest API. For example:
Authorization: token 87c3c7bb-045f-4f9d-a3a6-ba7c036ef70a
Message Size Limits
Listener accepts up to 1 MB of data for a single message. If you attempt to send more than 1 MB in a single data packet, Listener rejects the packet. Logs indicate if the pipeline rejected the packet due to size limits. If a Sync header is not used, a successful API response may be received, but it does not guarantee proper ingestion.
Because Listener performance can degrade with large message sizes, we recommend sending messages in the smallest possible size.
Listener is a real-time streaming system and does not support batch loading files. Data must be sent through the Ingest API.
Media Types
This API uses the JSON media type to transport data in all responses and supports JSON for all requests.
Ingest receives data in any data format. When sending a single message, Ingest does not attempt to parse or transform the data. When sending multiple messages at once, you can split them into individual messages using a custom delimiter or by sending a JSON array that is parsed and split into individual messages.
Confirmation of Receipt
By default, Ingest handles data asynchronously. Every data packet receives a UUID when it is sent to the router; however, UUIDs are not sent back. If the client requires a response with UUIDs to track messages through Listener and into its storage target, then you must send a request to Ingest with a Sync header with value 1. Waiting for UUID confirmations lengthens the request run time.
Sync: 1
If the Sync header is not sent or set to 1, then the client does not receive a response body.