API Contract Tester (Live Responses & HAR vs OpenAPI)

About the API Contract Tester (Live Responses & HAR vs OpenAPI)

Load an OpenAPI description (3.0, 3.1, 3.2 or Swagger 2.0) and check the API against it in one of three ways:

• Traffic: open a HAR file saved from your browser’s developer tools, a Newman JSON report or a Postman Collection Runner export. Nothing is sent anywhere: every recorded request to the API is matched to its operation and its response is checked.
• Live: choose operations and the page builds requests from the description’s examples and schemas — with your base URL and credentials, and optional negative cases such as a required parameter left out — and sends them straight from your browser, five a second by default.
• Checks: with or without a description, assert the status, a maximum time, a header or a JSONPath value on every request.

Each response is checked as the OpenAPI Specification describes: the status code is documented (an explicit code before its range, such as 2XX, before default), the content type is one the response documents, required headers are there, and a JSON body fits the response schema — JSON Schema 2020-12 for OpenAPI 3.1, the 3.0 dialect with nullable translated. The run lists operation coverage, requests the description does not document, undocumented status codes and properties the schema never mentions, and shows for each failure what the schema expects next to what came back.

Without a pass the result is a free preview: the summary counts and the first failures (up to three). The full report and the JUnit XML, HTML and Markdown exports unlock with a Premium pass.

How a response is matched and checked

The server’s base path is taken off the request URL (for https://api.example.org/v1 that is /v1), concrete paths are tried before templated ones (/pets/mine before /pets/{petId}), and a {variable} matches one path segment. A path that matches with another method is reported as an undocumented method; one that matches nothing, as an undocumented endpoint.

For the status, an explicit code wins over its range (2XX), and default covers codes not listed. For the media type, the most specific key wins (application/json, then application/*, then */*); a body where the response documents no content is a failure, and a header named Content-Type in headers is ignored, as the specification says. Required headers must be present. JSON bodies are checked against the schema with a full JSON Schema validator; in OpenAPI 3.0, nullable: true adds null to the type, boolean exclusiveMinimum and exclusiveMaximum are translated, and properties that are writeOnly do not count as required in a response. Other bodies are not checked and say so.

Live requests, CORS and safety

Live requests go from your browser, so the API must allow cross-origin requests from this page (CORS) — a local or staging server you can configure, or an API that already allows any origin. Only HTTPS addresses can be reached from this page. The browser also shows only the response headers an API lists in Access-Control-Expose-Headers, so a required header it hides is reported as not visible rather than missing.

Requests that change data (POST, PUT, PATCH, DELETE) are sent only after you confirm them; point live mode at a test environment, never at production data. Requests go out one after another at the rate you set (five a second by default). Tokens and keys stay in the page’s memory, are never stored, and are taken out of every report.

Recordings and what is kept out of reports

A HAR file is what the Network panel of Chrome, Edge, Firefox or Safari saves; save it “with content” so the bodies are in it. Requests to other hosts (scripts, fonts, analytics) are left out, and you can pick the API’s host. Before anything is shown or exported, URLs, headers and values are cleaned the way the HAR File Analyzer cleans them: cookies, Authorization and key headers, tokens in query strings and JWTs are replaced. A Newman JSON report has full responses; a Postman Collection Runner export has only status codes and times, so it is checked for those.

Sources

• OpenAPI Specification — Responses, Response, Media Type and Header Objects
• JSON Schema 2020-12 — the dialect of OpenAPI 3.1 schemas
• Newman — the JSON reporter

Limitations

• Only JSON bodies are checked against their schemas; XML, form and binary bodies are reported as not checked.
• Live requests reach only HTTPS APIs that allow cross-origin requests from this page; for others, record the traffic (for example with Newman or the browser’s developer tools) and use Traffic mode.
• Negative cases are simple (a required parameter left out, a number or boolean sent as text); they show whether the API validates input, not every rule it should enforce.
• Recordings up to 120 MB are read; a check that runs longer than 90 seconds is stopped.

Privacy

Sends data to online services

In live mode the requests you start go directly from your browser to the API you name — never through MySmartCoPilot. Recordings and descriptions are read in your browser and never uploaded; credentials are not stored.