XML Diff API¶
Overview¶
Compares two XML inputs as secure parser event streams and returns structural changes as JSONL. DTDs and entities are not supported.
Endpoint and authentication¶
POST https://api.apidatatools.com/xml-diff-api with x-api-key: YOUR_API_KEY.
Input modes¶
Body mode accepts {"left":"XML text","right":"XML text"}. URL mode uses left_url and right_url; file mode uses left_file and right_file. Accepted extensions are .xml, .txt, and .log.
Options¶
| Header | Default | Description |
|---|---|---|
x-ignore-whitespace | true | Normalize text-node whitespace. |
x-max-changes | 100000 | Change limit, clamped from 1 to 1,000,000. |
curl example¶
curl -X POST 'https://api.apidatatools.com/xml-diff-api' \
-H 'x-api-key: YOUR_API_KEY' \
--data-raw '{"left":"<root><value>1</value></root>","right":"<root><value>2</value></root>"}'
URL and file examples¶
curl --request POST --url https://api.apidatatools.com/xml-diff-api \
--header 'x-api-key: YOUR_API_KEY' --header 'x-source-type: url' \
--header 'x-ignore-whitespace: true' --header 'Content-Type: application/json' \
--data '{"left_url":"https://example.com/old.xml","right_url":"https://example.com/new.xml"}'
curl --request POST --url https://api.apidatatools.com/xml-diff-api \
--header 'x-api-key: YOUR_API_KEY' --header 'x-source-type: file' \
--header 'Content-Type: application/json' \
--data '{"left_file":"LEFT_UPLOAD_KEY","right_file":"RIGHT_UPLOAD_KEY"}'
Result and async process¶
The JSONL result contains metadata, structural changes with parser paths/events/values, and a summary with equal, changes, comparedTokens, and truncated. Body mode returns HTTP 200 with file and preview. Async submission returns HTTP 202 with job_id and status_url. Poll with the same API key; queued/processing includes retry_after, success includes result, and failure includes error.
Error handling¶
| HTTP status | Error codes |
|---|---|
400 | INVALID_SOURCE_TYPE, INVALID_BODY_ENCODING, EMPTY_BODY, INVALID_DIFF_BODY, INVALID_XML, XML_DTD_FORBIDDEN, EMPTY_DIFF_INPUT |
401 | UNAUTHORIZED |
404 | USER_NOT_FOUND, UNKNOWN_FUNCTION |
413 | PAYLOAD_TOO_LARGE |
429 | QUOTA_EXCEEDED, RATE_LIMITED |
500 | PLAN_NOT_FOUND, AUTH_ERROR, INTERNAL_ERROR |
Async errors include INVALID_DIFF_INPUTS, FILE_TOO_LARGE, CONFIG_ERROR, PLAN_CONFIG_ERROR, DOWNLOAD_FAILED, and UPLOAD_FAILED. Status errors include INVALID_JOB_ID, JOB_NOT_FOUND, FORBIDDEN, and DDB_ERROR.
Notes¶
DTDs and entities are rejected. Both sources are validated independently. Honor retry_after; plan limits and temporary retention apply.