Preserve the source artifact
Fetch the specification from the official URL and record retrieval time, final URL, content type, and a cryptographic hash. Keep the raw artifact or an immutable reference to it so a later diff can explain what changed.
Do not assume a file named openapi.json is valid or current. Parse it with an OpenAPI-aware validator and fail clearly on unsupported versions, unresolved references, or invalid schemas.
Resolve carefully
Specifications may split schemas across local and remote $ref values. Restrict remote resolution to expected HTTPS hosts, cap file size and nesting depth, and cache fetched references. This turns specification processing into controlled data ingestion instead of arbitrary network access.
Normalize for your goal
For a catalog, useful extracted fields include:
- title, version, and server URLs;
- authentication schemes;
- tags or resource groups;
- operation ID, method, and path;
- request and response content types;
- pagination hints and common errors;
- deprecation flags and external documentation.
Keep the original value and its source pointer when normalization could lose nuance.
Do not generate everything
A client generator may create thousands of types and methods; a documentation site may create thousands of thin operation pages. Generate only what has a consumer. API Atlas uses the spec to improve a concise provider profile and change detection, not to mirror an entire vendor reference.
Diff semantically
Formatting-only JSON or YAML changes are noise. Compare normalized operations, parameters, schemas, authentication, servers, and deprecation flags. Classify potential breaking changes such as removed operations, newly required parameters, narrowed enums, or incompatible response schemas.
Treat the diff as a review candidate. Specifications can contain mistakes, lag live behavior, or change accidentally.
Test generated clients
Pin the generator and specification hash. Compile generated code, run a contract fixture, inspect authentication injection, and verify nullable or union types in the target language. Regenerate in a clean directory so removed operations do not leave stale files behind.
The specification is a powerful source, but the official prose reference, changelog, and observed responses still matter when behavior is underspecified.
Observe client enum drift
The Alpaca TXSE asset-list case shows how a new server enum value can reject a whole typed response. Compare the installed client, the merged fix and the published release separately.