{"templateId":"../@theme/templates/BlogPost","sharedDataIds":{"blog-latest-posts":"blog-latest-posts"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"redocly_category":"Blog","type":"markdown","template":"../@theme/templates/BlogPost","title":"Catch API drift with the new proxy and drift commands","description":"Record real HTTP traffic with the proxy command, then let the drift command tell you where your API and your OpenAPI description disagree.","seo":{"title":"Catch API drift with the new proxy and drift commands","description":"Record real HTTP traffic with the proxy command, then let the drift command tell you where your API and your OpenAPI description disagree."},"author":{"id":"adam-sobaniec","name":"Adam Sobaniec","authorBIO":"Software Engineer, Redocly","image":"/assets/sobaniec.d72cecde632c015ce4db05cc559e1f27ccae55d6e5977f816362afb23a1a56a7.978384e4.png"},"publishedDate":"2026-07-08","categories":[{"category":{"id":"redocly","label":"Redocly"},"subcategory":{"id":"redocly-cli","label":"Redocly CLI"}},{"category":{"id":"redocly","label":"Redocly"},"subcategory":{"id":"product-updates","label":"Product updates"}},{"category":{"id":"api-testing","label":"API testing"},"subcategory":{"id":"integration-testing","label":"Integration testing"}}],"slug":"/blog/catch-api-drift"},"seo":{"title":"Catch API drift with the new proxy and drift commands","description":"Record real HTTP traffic with the proxy command, then let the drift command tell you where your API and your OpenAPI description disagree.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your OpenAPI description says one thing."," ","Your API does another."," ","Nobody notices, because nothing fails - until an SDK generated from that description breaks in a customer's build, or a partner integration chokes on a field that was \"documented\" but never returned."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The gap between what you describe and what you ship has a name: drift."," ","It accumulates quietly, one hotfix and one forgotten field at a time."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly CLI ships two commands that work together to close this gap: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["proxy"]}," records what your API actually does, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["drift"]}," compares it against what your OpenAPI description claims."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"record-first-judge-later","__idx":0},"children":["Record first, judge later"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["proxy"]}," command starts a local reverse proxy in front of your API."," ","Point any client at it - a browser, a test suite, a curl script - and every request and response that passes through is captured into a standard HAR file."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["drift"]}," command takes that traffic and replays it against your OpenAPI description."," ","It matches each exchange to a documented operation and reports the discrepancies: undocumented endpoints, undocumented parameters, missing required fields, response bodies that don't match their schemas."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Because the two commands meet at a plain HAR file, you don't have to use them together."," ","Traffic exported from browser DevTools, Kong, or Nginx/Apache JSON logs works with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["drift"]}," too."," ","And if you prefer immediate feedback, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["proxy"]}," accepts an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--api"]}," flag and validates traffic live, as it flows."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"HAR files record everything"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A HAR file is a full capture: request and response headers, cookies, tokens, and bodies all land in it verbatim."," ","Run ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["proxy"]}," and handle the recorded HAR files in closed sandboxes - a local machine or an isolated e2e environment exercised with synthetic accounts and test credentials - so no real user data or production secrets end up in the recording."," ","If you do record traffic that touches real credentials, treat the HAR file like a secret: keep it out of version control, redact it before sharing, and delete it when you're done."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"put-it-in-your-test-pipeline","__idx":1},"children":["Put it in your test pipeline"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Here is the setup we like most: you probably already have e2e or integration tests that exercise your API."," ","That traffic is a free, realistic sample of how your API actually behaves - you're just letting it evaporate after every run."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Instead, start ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["proxy"]}," before the test run, route the tests through it, and stop it when they finish."," ","The proxy sits between your tests and the API: requests and responses pass through it unchanged, and every exchange is captured on the way."]},{"$$mdtype":"Tag","name":"Diagram","attributes":{"data-language":"mermaid","align":"center","diagramType":"mermaid","diagramSource":"flowchart TD\n tests[\"E2E / integration tests\"] -->|\"connects to http://localhost:4040\"| proxy[\"redocly proxy\"]\n proxy -->|\"proxies to http://localhost:9000\"| target[\"Your API\"]\n proxy -.->|\"records\"| har[\"test-traffic.har\"]\n har --> drift[\"redocly drift\"]\n openapi[\"openapi.yaml\"] --> drift\n drift -->|\"produces\"| report[\"✨ Drift report  \"]\n","diagramHtml":"

connects to http://localhost:4040

proxies to http://localhost:9000

records

produces

E2E / integration tests

redocly proxy

Your API

test-traffic.har

redocly drift

openapi.yaml

✨ Drift report  

","diagramHtmlDark":"

connects to http://localhost:4040

proxies to http://localhost:9000

records

produces

E2E / integration tests

redocly proxy

Your API

test-traffic.har

redocly drift

openapi.yaml

✨ Drift report  

"},"children":["flowchart TD\n tests[\"E2E / integration tests\"] -->|\"connects to http://localhost:4040\"| proxy[\"redocly proxy\"]\n proxy -->|\"proxies to http://localhost:9000\"| target[\"Your API\"]\n proxy -.->|\"records\"| har[\"test-traffic.har\"]\n har --> drift[\"redocly drift\"]\n openapi[\"openapi.yaml\"] --> drift\n drift -->|\"produces\"| report[\"✨ Drift report  \"]\n"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In a script, the whole setup fits in a few lines:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly proxy --target http://localhost:9000 --har ./test-traffic.har &\nPROXY_PID=$!\n# run your e2e or integration tests against http://localhost:4040\nkill \"$PROXY_PID\" && wait \"$PROXY_PID\"\nredocly drift ./test-traffic.har --api ./openapi.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kill"]}," step matters: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["proxy"]}," streams captured exchanges to a temporary file and assembles the final HAR only on a clean shutdown, so ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["drift"]}," finds nothing to read until the proxy has stopped."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["drift"]}," command exits with a non-zero code when it finds error-level problems, so it slots into CI as a gate."," ","Every test run now doubles as a contract check, with zero extra test code to maintain."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"try-it-on-the-cafe-api","__idx":2},"children":["Try it on the Cafe API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You don't need your own API to see it work."," ","Redocly Cafe is our public demo API, and its OpenAPI description is published along with the docs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Start a proxy in front of the live Cafe API:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly proxy --target https://api.cafe.redocly.com --har ./cafe.har\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Proxy listening on http://localhost:4040 → forwarding to https://api.cafe.redocly.com/\nRecording traffic to ./cafe.har\nPress Ctrl+C to stop.\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send some traffic through it:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl http://localhost:4040/menu\ncurl \"http://localhost:4040/menu?category=dessert\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Press ",{"$$mdtype":"Tag","name":"kbd","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Ctrl"]}]}," + ",{"$$mdtype":"Tag","name":"kbd","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["C"]}]}," and the proxy writes the HAR file:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Captured 2 exchange(s) to ./cafe.har\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Now grab the Cafe OpenAPI description:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -s https://cafe.redocly.com/page-data/shared/oas-openapi/cafe.yaml.json \\\n | jq .definition > cafe-openapi.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To simulate drift, open ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cafe-openapi.json"]}," and make the description lie:"," ","in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Page"]}," schema, change the type of the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}," property from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["integer"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["string"]},"."," ","Then replay the recorded traffic against it:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly drift ./cafe.har --api ./cafe-openapi.json\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"┃ Exchanges: total=2 documented=2 undocumented=0\n┃ Findings: total=3 error=2 warning=1 info=0\n\n✖ ERROR ×2 → Response field \"page.total\" must be string.\n ↳ sample exchange=0 GET /menu (200) listMenuItems\n expected: type \"string\"\n actual: 5\n\n▲ WARN → Undocumented query parameter in traffic: \"category\"\n ↳ sample exchange=1 GET /menu (200) listMenuItems\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The error is the discrepancy we planted: the API returns a number where the description now promises a string."," ","The warning is a bonus we didn't plant at all."," ","The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["category"]}," query parameter we sent isn't documented anywhere in the Cafe description."," ","Two requests of traffic, and drift already surfaced something real."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"more-than-schemas","__idx":3},"children":["More than schemas"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Findings come from built-in rules that you can select with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--rules"]}," flag:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["undocumented-endpoint"]}," flags traffic that doesn't match any documented operation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema-consistency"]}," validates parameters, headers, and request/response bodies against your schemas."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["security-baseline"]}," checks that requests actually satisfy the security requirements your description declares, and flags things like credentials sent over plain HTTP."," ","Loopback hosts such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["localhost"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["127.0.0.1"]}," are exempt from the transport check, so sandboxed recordings against a local target stay warning-free."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["owasp-api-top10"]}," scans recorded traffic with heuristics based on the OWASP API Security Top 10 - enable it with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["--rules owasp-api-top10"]},". It looks for credential-like query parameters, insecure CORS (wildcard origin with credentials enabled), weak cookie attributes, sensitive-looking fields in response payloads, and large unpaginated responses."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["One caveat before you wire ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["owasp-api-top10"]}," into a CI gate: it inspects each exchange in isolation."," ","It has no notion of user identity or ownership across requests, so it cannot detect authorization logic flaws like Broken Object Level Authorization."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reports come out as human-readable text, JSON, CSV, or SARIF, so the same run can feed a terminal, a dashboard, or a code-scanning integration."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Experimental"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both commands are experimental."," ","Flags, output formats, and behavior may change - including breaking changes - in upcoming releases while we shape them with your feedback."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"get-started","__idx":4},"children":["Get started"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["proxy"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["drift"]}," commands are available now in the latest ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli"},"children":["Redocly CLI"]},"."," ","Check out the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/commands/drift"},"children":["drift"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://redocly.com/docs/cli/commands/proxy"},"children":["proxy"]}," command references, run them against your own traffic, and tell us what you find - feedback and ideas are welcome on the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/Redocly/redocly-cli/issues"},"children":["Redocly CLI GitHub repository"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your API and its description should tell the same story."," ","Now you can check."]}]},"headings":[{"value":"Record first, judge later","id":"record-first-judge-later","depth":2},{"value":"Put it in your test pipeline","id":"put-it-in-your-test-pipeline","depth":2},{"value":"Try it on the Cafe API","id":"try-it-on-the-cafe-api","depth":2},{"value":"More than schemas","id":"more-than-schemas","depth":2},{"value":"Get started","id":"get-started","depth":2}],"frontmatter":{"template":"../@theme/templates/BlogPost","title":"Catch API drift with the new proxy and drift commands","description":"Record real HTTP traffic with the proxy command, then let the drift command tell you where your API and your OpenAPI description disagree.","seo":{"title":"Catch API drift with the new proxy and drift commands","description":"Record real HTTP traffic with the proxy command, then let the drift command tell you where your API and your OpenAPI description disagree."},"author":"adam-sobaniec","publishedDate":"2026-07-08","categories":["redocly:redocly-cli","redocly:product-updates","api-testing:integration-testing"]},"lastModified":"2026-07-21T13:09:30.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/blog/catch-api-drift","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}