Skip to main content

Test Pipe

POST /public/v1/pipes/test​

Checks with one record whether a pipe would work. The request reads a record from the source topic and takes it through the pipe: decoding, the processing of the topic view, and encoding for the target topic.

Nothing is written, no position is committed and no pipe is created.


Request​

The body is the same as for Create Pipe. The same rights are checked.


Example Request​

curl --location 'https://your-instance.com/public/v1/pipes/test' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your-api-key>' \
--data-raw '{
"name": "Fix account ids",
"mode": "ONCE",
"source": { "serverId": 1, "viewId": 42 },
"target": { "serverId": 1, "topic": "payments" },
"configuration": {
"target": { "keyCodec": "String", "valueCodec": "Json" }
}
}'

Response​

HTTP Status Code: 200 OK

The status code is 200 whether the test passed or not. Check the field ok.

FieldTypeDescription
okbooleantrue if a record made it through all stages
scannedintegerNumber of records read during the test. Up to 500 records are read to find one that passes the filters of the view.
stagesarray of objects (Stage)The stages of the test, in their order, up to the one that failed
outputobjectWith ok true: the record the pipe would write
inputobjectWith a failed stage: the record it failed on, as far as it was decoded

Stage Structure​

FieldTypeDescription
stagestringsource, target, decode, process, encode, or setup for a problem before the first record
okbooleanWhether the stage passed
messagestringWhat was checked, or what went wrong

Output Structure​

FieldTypeDescription
recordobjectThe record after the processing of the view, as the Data Explorer shows it
headersarray of objectsThe headers that would be written: key, value
keyBytesintegerSize of the encoded key in bytes, -1 without a key
valueBytesintegerSize of the encoded value in bytes, -1 without a value

Example Response — Passed​

{
"ok": true,
"scanned": 1,
"stages": [
{ "stage": "source", "ok": true, "message": "The source topic can be read." },
{ "stage": "target", "ok": true, "message": "The target topic exists." },
{ "stage": "decode", "ok": true, "message": "The record can be decoded." },
{ "stage": "process", "ok": true, "message": "The processing of the topic view runs." },
{ "stage": "encode", "ok": true, "message": "The result can be written with the codecs of the target." }
],
"output": {
"record": {
"topic": "payments.dlq",
"partition": 0,
"offset": 118,
"timestamp": 1794536317279,
"key": "DE4410",
"value": { "accountId": "DE4410", "amount": 120.0 },
"keyDecoder": "String",
"valueDecoder": "Json"
},
"headers": [],
"keyBytes": 6,
"valueBytes": 39
}
}

Example Response — Failed​

{
"ok": false,
"scanned": 0,
"stages": [
{ "stage": "source", "ok": true, "message": "The source topic can be read." },
{ "stage": "setup", "ok": false, "message": "The target topic 'payments' cannot be reached: UnknownTopicOrPartitionException: This server does not host this topic-partition." }
]
}

Possible Errors​

Status CodeDescriptionSolution
400The request body is not validCheck the request body
401UnauthorizedCheck your API key
403The API key lacks a right for a topic or the Schema RegistryCheck the rights of the API key
404A connection or the saved view does not exist or is not visibleCheck the IDs

Best Practices​

  • Run the test in your deployment pipeline before every Create Pipe request, and stop if ok is false.
  • A test needs at least one record in the part of the source topic the pipe would read. With an empty topic the stage decode fails with a message that says so.