OpenAPI Paths and Operations: Build an Endpoint Inventory
Extract an API endpoint list from OpenAPI JSON without confusing path metadata, references or HTTP operations.
An API inventory should identify each supported method and path together. GET /users and POST /users are separate operations even though they share a resource path. OpenAPI puts these definitions under the paths object, alongside path-level metadata and sometimes references. A small operation list helps reviewers navigate a large description, but it should retain enough context to avoid overstating what has actually been resolved.
Treat a method and path as one operation
Walk each path item and inspect its HTTP method fields. Keep the method, exact templated path, operation identifier, summary, tags and deprecation marker. A parameters array at the path level is shared configuration rather than an additional endpoint. Likewise, a summary or vendor extension is not an operation. Preserve path templates such as /users/{id} instead of replacing them with an example identifier. The inventory should describe the API contract, not a single observed request.
Handle referenced definitions explicitly
A path item may refer to a definition elsewhere. Reading only its local properties can therefore miss operations. Our extractor lists unresolved path references instead of fetching remote documents or pretending that the inventory is complete. It also excludes callbacks and webhooks from the paths inventory. If you need a complete dependency-resolved description, use a dedicated OpenAPI processor with an explicit reference-resolution policy, then inspect its resulting document. Resolving references is a separate task from collecting visible method entries.
Use the inventory as a review aid
Compare the extracted list with the intended migration or release scope. Deprecated operations can be prioritized for client review, while missing operation identifiers may make generated clients less convenient. An operation list does not establish whether authentication, response schemas or parameters are correct. Keep the full source document alongside the report and validate it with tooling appropriate to its OpenAPI version. Our extractor accepts JSON documents; convert YAML carefully before use and retain meaningful string values and reference paths.
Worked example
{"openapi":"3.1.0","paths":{"/users":{"get":{"operationId":"listUsers"},"post":{"operationId":"createUser"}}}}
Inventory: GET /users; POST /usersDoes an empty inventory prove that an API has no operations?
No. The document may use unresolved references or describe other features outside the inspected paths. Check the source and the extractor’s unresolved-reference report.
Reference and further reading
KEEP EXPLORING
Another useful idea.
How to Flatten Nested JSON Without Losing Structure
Flatten nested JSON for exports and debugging while preserving arrays, empty containers, and keys that contain dots.
JSON Pointer Explained: Paths, Arrays and Escaped Keys
Learn JSON Pointer syntax, including /0 array indexes, ~0 and ~1 escaping, and the empty root pointer.
JSON vs NDJSON: When to Use JSON Lines
Compare JSON arrays and newline-delimited JSON for logs, streaming APIs, exports, and incremental processing.