API specs (OpenAPI)

With Wirescry Pro, the APIs tab holds your OpenAPI specs. Traffic to a spec's base URLs is checked against it as it arrives: its parameters, its status code, and its request and response bodies. Each request a spec describes gets a badge in the traffic list, and the detail pane says what matched and what didn't.

Wirescry only reads your specs. It doesn't change the traffic, and it doesn't change the spec files.

Adding a spec

Click Add a spec… and choose a .json, .yaml or .yml file. Wirescry reads OpenAPI 3.0, 3.1 and 3.2, in JSON or YAML. When it's added, the tab says how many operations it found.

• OpenAPI 3.2 specs are checked with 3.1's rules. What 3.2 adds isn't checked: the QUERY method, additionalOperations, querystring parameters and streamed media (itemSchema). Requests to QUERY and additional operations get no badge.
• Swagger 2.0 isn't supported. Convert the spec to OpenAPI 3 first, then add that.
• In JSON, the openapi version must be a string, such as "3.1.0", not a number.
• In YAML, a key written twice in one object is refused. In JSON, the last one counts, and the tab says which keys were repeated.

The list shows each spec's title and version, with its number of operations and base URLs. Select one to see its source file, OpenAPI version, operation count and when it was read.

Specs in several files

A spec can pull in other files with $ref, such as $ref: schemas/pet.yaml#/Pet. Wirescry follows those references when:

• the file is a .json, .yaml or .yml file,
• it's in the spec's own folder or a folder below it, with no .. out of it, no absolute path and no link that leads outside it,
• and the spec pulls in no more than 200 other files.

Web addresses aren't fetched, and $refs to anchors (such as #pet) aren't followed. The tab lists each $ref it couldn't follow, and why, under Worth knowing. What it points at isn't checked.

Worth knowing

Under Worth knowing, the tab lists things about a spec that affect its checks, such as:

• $refs that aren't followed, or that point at nothing in the spec.
• Servers that are skipped, because a variable in them has no default.
• nullable in an OpenAPI 3.1 spec. 3.1 doesn't have it, so it's ignored, and null values there are flagged. Use type: [..., "null"] instead.
• Patterns that can't be run safely, such as ones with backreferences or \p{…}. They're skipped.
• A spec with no paths, which no traffic matches.

Reload, Remove and Off

Wirescry checks traffic against its own copy of the spec, made when you added it. Changing, moving or deleting the source file changes nothing until you click Reload, which reads the file again. A reload keeps the spec's on/off setting and your base URLs. If the file can't be read, Wirescry says why and goes on using the copy it had.

Remove takes the spec out of Wirescry and its badges off the traffic list. The source file is kept.

The checkbox on each row turns checking against that spec off and on. A spec that's off can still fill in Compose.

The same spec twice

The same file can't be added twice, even under another spelling of its path; use Reload instead. The same spec (the same title and version) from another file can be added, for example a newer draft. Wirescry says so, and traffic that both match is checked against the one listed first.

Limits

	Limit
Specs	20
Spec file	32 MB, together with the files its $refs pull in
Other files a spec pulls in	200
Wirescry's copy of one spec	48 MB as JSON
All specs	64 MB together, as Wirescry keeps them
Operations	10,000 per spec
Servers	The first 50 in a spec are used
Your base URLs	20 per spec
Base URLs matched	200 per spec, its servers and yours together
Nesting	128 levels

A file must also be read within two minutes. A very large YAML file can need more memory than Wirescry allows a spec. The same spec as JSON takes much less, so convert it and add that.

Base URLs and matching

A spec matches traffic to its base URLs: the spec's own servers that are full URLs, and any base URLs you add under Your base URLs, such as http://localhost:3000. Server variables are filled in with their defaults. A base URL starts with http:// or https://. A query or fragment is dropped; a user name or password isn't allowed.

Relative servers, such as /v1, are added to each of your base URLs: http://localhost:3000 and /v1 match http://localhost:3000/v1. A spec whose servers are all relative, or that has none, matches nothing until you add a base URL. The tab says so.

An operation or path with its own servers is matched on those, instead of the spec's.

For each request, Wirescry:

1. Finds a base URL with the same scheme, host and port, whose path starts the request's path. Host names ignore case.
2. Matches the rest of the path against the spec's paths. Paths are case-sensitive, and the most specific one wins: /pets/mine before /pets/{id}. A segment can mix text and parameters, such as {name}.json.
3. Then the method. A HEAD request uses the GET operation if the path has no HEAD one, and its response body isn't checked.

When several specs or base URLs match, a matched operation wins, then the longer base URL, then the more specific path.

These get no badge:

• An OPTIONS request to a path with no OPTIONS operation, such as a browser's CORS preflight.
• WebSocket connections.
• Requests that match no base URL of a spec that's on.

Badges

A request a spec describes gets one of these badges, before the path in the traffic list. Hover over it for more.

Badge	What it means	On hover
Spec	It matches an operation, and nothing checked was wrong.	The operation and spec, e.g. "Matches GET /pets/{id} in Petstore 1.0.0."
Spec, partly	Nothing checked was wrong, but part of it couldn't be checked, such as a body over 2 MB, or a request that got no complete response.	Why
Spec: 2 issues	Something doesn't match the spec. Counts up to 50.	The first issue, and how many more
Not in spec	The base URL matched, but no operation in the spec has this method and path. It may be missing from the spec.	The method and path the spec doesn't have
Spec: unchecked	The checker failed on it, so it wasn't checked at all.	Why

A request gets at most one of these. The traffic list shows up to three plugin badges on a row, beside its own badges such as Sent.

In the detail pane

Select a request with a badge, and its details have an API spec section: the spec, the operation (its method and path, operation ID and summary), and:

• Matches the spec, or the issues found, under Request and Response, each with where it is (such as query limit or body /items/0/id) and what's wrong.
• Notes: what wasn't checked, and why.

Results are kept for the most recent 10,000 exchanges, as the traffic list is. When you add, reload, remove or turn off a spec, or change its base URLs, the traffic in the list is checked again, newest first.

What's checked

The request

• Path, query and header parameters against their schemas. Values are read as their style and explode say (form, simple, label, matrix, spaceDelimited, pipeDelimited and deepObject), and as the type the schema wants, so ?limit=10 is a number.
• Required parameters that are missing: query, header and cookie. For cookies, only that they're there; their values aren't checked.
• The body: missing when it's required; a Content-Type that's missing or that the spec doesn't list; and JSON bodies against their schema.

Header parameters named Accept, Content-Type and Authorization are ignored, as OpenAPI says. Parameters the spec doesn't list aren't flagged.

The response

• The status must be one the operation documents: exactly, as a range such as 4XX, or as default. An operation that lists no responses isn't checked here.
• The Content-Type must be one the spec lists for that status.
• JSON bodies are checked against their schema.

Response headers other than Content-Type aren't checked.

If the request failed, or its response was cut off, there was no complete response, so the response isn't checked and the badge reads Spec, partly. The request is still checked, so its issues still show as Spec: N issues.

Bodies

Only JSON bodies are checked against their schema: application/json, and types ending in +json. For other bodies, only the Content-Type is checked, and a note says the body wasn't.

A body isn't checked, and the badge reads Spec, partly, when it:

• is over 2 MB once decoded,
• was too large for Wirescry to keep in full,
• couldn't be decoded, or
• is no longer stored.

A body that isn't valid JSON is an issue. An empty one isn't checked.

Schemas

Schemas are checked as JSON Schema, with OpenAPI's additions: nullable in 3.0, readOnly properties aren't required in requests and writeOnly ones aren't required in responses, and discriminator picks the schema to check against. Some things aren't checked:

• Formats, such as date-time or email, are ignored, as JSON Schema does by default.
• Patterns run on an engine that can't be slowed down by them. One that needs more, such as backreferences or \p{…}, is skipped. A pattern also isn't checked on very long text, or on text with emoji and other characters it can't read safely.
• $refs that aren't followed (see above) leave that part unchecked.
• Very large or complex bodies: a check that would take too long stops part way, and the badge reads Spec, partly.

An exchange shows up to 50 issues.

Issues and notes

An issue is something that doesn't match the spec, and counts toward Spec: N issues. A note is something worth knowing that isn't counted, and doesn't change the badge. For example:

• A 4xx or 5xx status the spec doesn't document is an issue if the operation documents some errors (any 4xx or 5xx status, or default). If it documents none, as many specs don't, it's a note. Any other status the spec doesn't document is an issue.
• 304 and 1xx statuses are never an issue.
• A body that isn't JSON, or a pattern that was skipped, is a note.

Spec, partly means no issues were found, but part of the exchange couldn't be checked: no complete response (the request failed or was cut off), a body that wasn't checked, a check that stopped part way, or a discriminator that names a schema the spec doesn't have. If there are issues as well, the badge shows them.

When checking pauses

Checks run one at a time, in the background, on a thread of their own, so the proxy never waits for them. New traffic is checked first. A spec can take up to a minute to load for checking, and each check up to two seconds.

A check that fails gets Spec: unchecked: it took too long, its spec took over a minute to load, its spec couldn't be loaded for checking, or the checker ran out of memory, crashed or couldn't start. After three failures in a row, checking pauses for a minute. Each further failure before a success pauses it again, for two minutes, then five. A check that succeeds starts the count again.

While checking is paused, the APIs tab says why and when it tries again, with Try now. Requests that match an operation meanwhile get no badge until it resumes; then they're checked.

Filling in Compose from a spec

In the panel beside the Compose tab's editor, From an API spec fills the composer with a request for one of a spec's operations:

1. Choose a Spec.
2. Choose a Base URL: one of its base URLs, as the APIs tab lists them, or the {{baseUrl}} variable.
3. Type in Find an operation, such as GET /pets or createPet. Every word must appear in the method, path, operation ID or summary. Up to 100 operations are listed.
4. Click one.

The request it makes has:

• The method and URL, with each path parameter as a variable: /pets/{id} becomes /pets/{{id}}.
• Required query and header parameters, as {{name}} variables. Optional ones are left out, and so are cookie parameters and Accept, Content-Type and Authorization header parameters.
• Content-Type from the operation's first request media type, unless it has a wildcard, such as */*.
• A body: the spec's example for that media type, or, for JSON, one made from its schema, with its required properties set to the schema's example, default or first allowed value, or to a placeholder: "" (or one for its format, e.g. user@example.com for email), the lowest number allowed, or false. Properties marked readOnly are left out. A body over 512 KB is left out.

Characters other than letters, digits, _, . and - in a parameter's name become _ in its variable. Fill the variables in from an environment.

If the composer has changes that aren't saved, Wirescry asks before replacing them. Nothing is sent until you click Send, and the request isn't saved until you save it.

Where specs are stored

In the plugins/pro folder of Wirescry's data folder:

File or folder	What it holds
apis.json	The list of specs: each one's source path, whether it's on, your base URLs, and what the tab shows about it.
apis/	Wirescry's copy of each spec, as JSON, one file per spec.

A copy holds the spec's openapi, info, servers, paths and components, with any files its $refs pulled in. That includes the descriptions, examples and server URLs in it. The files are unencrypted. Remove deletes a spec's copy. Wirescry never sends a spec anywhere.

If apis.json can't be read, Wirescry handles it as it does saved requests, and says so in the tab.

When Pro is locked

Without an active license, the APIs tab shows what it does and how to start a trial or enter a key, and so does the panel beside the Compose editor. Traffic isn't checked, and Pro's badges come off the traffic list.

Your specs and their settings are kept. When Pro is active again, the traffic still in the list is checked again.

Troubleshooting

What you see	What to check
No badge appears	Is the spec on, and does the APIs tab list a base URL for the request's scheme, host and port? A spec with relative servers, or none, needs a base URL of yours. OPTIONS preflights, WebSockets and OpenAPI 3.2's QUERY get no badge. Also check that checking isn't paused, and that Pro is active.
Not in spec on an endpoint that works	The spec may not have that method or path, or the source file changed since it was read: click Reload. Check the base URL's path too: if it ends in /v1 and the spec's paths start with /v1, the request would need /v1/v1. Paths are case-sensitive.
Spec, partly	Open the API spec section: the notes say what wasn't checked. Often a body over 2 MB, one no longer stored, or a request that failed.
A null value flagged in a 3.1 spec	3.1 ignores nullable. Use type: [..., "null"].
Spec: unchecked, or "Checking is paused"	The checker failed; the API spec section and the APIs tab say why. After three failures in a row it pauses, then tries again on its own. Try now tries at once.
A spec says "Can't be used"	Wirescry's copy of it couldn't be loaded. Click Reload to read the source file again.
"Checking is off: part of Wirescry Pro is missing"	Reinstall Wirescry.