Reverse-Engineering APIs in Real Time: How OpenAPI DevTools Turns Browser Traffic Into Specifications

Hook

Most developers have stared at an undocumented third-party API wondering what it actually returns. OpenAPI DevTools flips the script: just browse normally, and watch a complete API specification build itself in real time.

Context

The OpenAPI specification has become the de facto standard for describing RESTful APIs, but creating one manually is tedious and error-prone. You document each endpoint, parameter, and response shape by hand—and the spec becomes stale the moment the API changes. Worse, when you’re integrating with third-party services that lack documentation, you’re left inspecting network tabs and taking notes in a text file.

OpenAPI DevTools emerged from this frustration. Rather than manually documenting APIs, it observes actual HTTP traffic as you browse and automatically infers the specification. Every JSON request your browser makes becomes data: endpoints, headers, query parameters, request bodies, and response shapes all get captured and merged into a living OpenAPI 3.1 document. It’s reverse-engineering as a passive activity, turning exploration into documentation.

Technical Insight

The extension operates as a DevTools panel that intercepts network requests. As each request completes, the tool extracts JSON payloads from both requests and responses, then uses schema inference to build OpenAPI specification fragments. The core challenge is schema merging—when the same endpoint returns different shapes across multiple requests.

Consider an API that returns user objects where a field is sometimes a string and sometimes null. OpenAPI DevTools tracks every variation it observes, then reconciles them into a schema that represents all possibilities. This approach means the specification grows more accurate with exposure. The first request might show a field as a string, the second reveals it can be null, and subsequent requests continue refining the schema without discarding previous information.

Path parameterization presents another design challenge. URLs like /users/123/posts/456 and /users/789/posts/101 represent the same endpoint with different parameters, but the tool can’t automatically distinguish dynamic segments from static paths. The solution is manual interaction: click any URL segment in the UI to convert it into a path parameter like /users/{userId}/posts/{postId}. Once marked, the tool automatically consolidates all matching requests—past and future—under that parameterized endpoint. As the README notes, this process is irreversible within a session.

The specification renders live using Redoc, an OpenAPI documentation renderer that updates in real time as new requests fire. This creates a tight feedback loop: browse to a new page, watch requests appear in the DevTools network tab, and simultaneously see the specification expand with new endpoints and schemas. The tool supports session persistence through export/import functionality. The entire specification and internal state serialize to JSON, enabling you to save progress, share specs with teammates, or resume analysis sessions across browser restarts.

Gotcha

OpenAPI DevTools has clear boundaries that stem from its browser-based architecture. It only captures JSON-based requests—other API formats won’t appear in the generated specification. If you’re working with an API that mixes JSON and other response types, you’ll get an incomplete specification.

Path parameterization is entirely manual. As the README explicitly states, this process is irreversible—if you accidentally mark a static path segment as a parameter, you must clear the entire specification and start over. This becomes challenging when exploring large applications with hundreds of endpoints. The tool also can’t automatically detect patterns like /users/active versus /users/123; you need domain knowledge to distinguish static routes from dynamic ones.

The browser-based design limits traffic visibility to requests the current tab makes. For comprehensive API discovery across an entire system beyond what’s visible in the browser, you’d need different tooling. The README explicitly acknowledges these limitations and points users toward the successor project, demystify, which addresses them with proxy support (enabling desktop app usage), HAR file processing, automatic path parameter detection, and the ability to reverse engineer other HTTP-based standards.

Verdict

Use if you’re reverse-engineering web APIs without documentation, auditing third-party integrations to understand actual behavior versus claimed behavior, or generating baseline OpenAPI specs for legacy services during modernization projects. It’s valuable for security researchers exploring API attack surfaces and developers debugging unexpected API responses. Skip if you need comprehensive coverage beyond browser-observable traffic, work primarily with non-JSON protocols, or require automated path parameter detection for large-scale API discovery. For new projects, strongly consider demystify—the successor project adds proxy support for desktop app usage, HAR file analysis, automatic path parameter detection, and the ability to reverse engineer other HTTP-based standards. OpenAPI DevTools remains useful for lightweight, browser-only reverse engineering, but demystify represents the evolution of this approach with significantly expanded capabilities.