Help › Guide
Discovery
Reqlyn 0.5.1 is not released yet. This help describes it ahead of release.
Discovery, the compass on the rail, is where an unfamiliar API is learned from what you already have: traffic recorded in a browser, a Postman collection, an OpenAPI description, or recordings of a task done by hand. Nothing in an imported file is sent, fetched or run, and likely secrets are masked as the file is read. A Postman, Insomnia or Bruno collection's scripts are translated, not run here: a collection is taken as an operation, its scripts with it, in Operations (Operations).
Importing a file
"Choose a file…" takes:
- a HAR file saved from a browser's network panel;
- a Postman collection, exported as Collection v2.1, or kept as Collection 3.0, Postman's Git-native YAML: choose any
.request.yamlfile in it, or a.resources/definition.yaml, and the whole collection is read, from the folder undercollections(as Postman keeps them) or else the highest folder with a definition of its own, in the order itsorderfields give, scripts translated and secrets masked as a v2.1 collection's are (saved examples are not read); or a Postman environment or globals export; - an Insomnia export: v4 (JSON) or a v5 collection (YAML);
- a Bruno collection, exported from Bruno as one JSON file, or kept as Bruno keeps it, a folder of
.brufiles: choose any.brufile in it, or itsbruno.json, and the whole collection is read, from the folder that holdsbruno.json(hidden folders andnode_modulespassed over, links not followed); or kept as OpenCollection YAML, Bruno's default since 3.1: choose itsopencollection.ymlor any request's.ymlfile in it, and the folder holdingopencollection.ymlis read the same way, scripts and assertions translated as a.brucollection's are; - an OpenAPI 3.0 or 3.1 description, in JSON or YAML;
- a WSDL 1.1 description of a SOAP service, whatever its file is called: each operation of its SOAP port (SOAP 1.1 when it has one, else 1.2) becomes a POST to the port's address, with its
SOAPAction(or SOAP 1.2'saction), its content type, and an envelope whose elements are{{placeholders}}named as the schema names them, qualified as it says; document and rpc style; - requests exported from Reqlyn.
A curl command line is imported from the command palette's "Import a curl command".
The import is reviewed before anything is created. The review shows the source, the requests captured, which can be imported and which were excluded (and why), and what was masked: likely secrets, cookies and authorization headers are replaced as the file is read, and a masked value becomes a {{variable}} for you to fill. You accept, change or leave out each candidate, and the requests are created only when you confirm. What an importer cannot read stays visible in the import report.
A Postman environment holds no request: its page lists its variables, and "Make the environment" makes a Reqlyn environment of them, named as in Postman, and chooses it for requests, so the {{name}} placeholders of a collection imported with it are filled. A variable Postman marks secret, or one whose name looks secret (token, api_key), is a secret variable: its value goes to the secret store and is not shown. A variable turned off in Postman, or one whose name Reqlyn does not take, is left out and said. A file saved with a byte-order mark, as Windows editors often save one, is read as any other.
OpenAPI references inside the file are followed; a reference to another file or an address is not fetched.
Endpoints and evidence
Recorded traffic is grouped into endpoints, each with the path parameters proposed for it, such as /devices/{id} from /devices/4831 and /devices/4832. You can edit the path. Selecting an endpoint shows:
- the samples it was inferred from, with when each was seen and its secrets masked;
- the fields observed in its requests and responses, with how often each was seen and its types;
- its documentation differences, when an OpenAPI description is held against it.
Evidence is labeled for what it is: Documented, Observed, Inferred, or Engineer verified. There is no confidence score. A field seen in every sample is not thereby required: successful examples cannot show what an API requires, and Reqlyn says so.
Held against an OpenAPI description, an endpoint's differences are listed as questions, kept apart: something undocumented, behavior the documentation contradicts, and a documented case never seen.
Exports
Requests can be exported as curl, as Reqlyn's own definitions, and as a reviewed OpenAPI description made from the endpoints. Exports mask what imports mask.
A task from recordings
When you do the same task two or more times with different values (say, looking up two different devices), each recording holds the same calls with different values. "Compare recordings of one task…" chooses two or more HAR files and lines them up:
- The calls every recording makes, numbered, in order.
- The values that flow: a value one response gives that a later call sends, such as an id or a token, said as a sentence. Only flows seen in every recording are kept.
- What was set aside: analytics and telemetry, calls not in every recording, and a browser's CORS preflights, each with why.
- A draft operation, step by step. What differs between recordings becomes an input (typed as an integer when every recording sent a whole number). What a response gives becomes a mapping from that step. A masked value becomes an environment variable. What is the same everywhere stays as written. Each part says what it rests on, and the values each recording sent, never a secret's.
- Recipes offered: a list read in pages becomes the step's paging (the only offer applied); a login is offered as a Login credential; a call asked until its answer changed is offered as a step that waits; an error answer is offered as a "fails when" rule.
- What it assumes, in the warning color.
- Review: an example of each call, request and answer, masked; "Show the OpenAPI description" shows the calls described as OpenAPI 3.1.
"Save as an operation" saves the draft and its requests, in a folder "From recordings: <name>". Nothing is sent.
From the command line: reqlyn demonstrate first.har second.har --save "Device lookup".
Questions the recordings leave open
Recordings cannot say everything: whether a query value is needed, how a paged list ends, what an item that is not there gives. "Questions the recordings leave open" lists each such question with the one GET that would answer it, at most ten. Nothing else is ever proposed, and nothing is sent until you press "Send these N reads"; then each answer is said. A login is never sent to get a token. From the command line: reqlyn demonstrate … --probe, and --yes to send.
Checking on a third recording
"Check on a third recording…" takes a recording the draft was not made from. It reads the inputs that recording sent and what it ended with, and names the steps that write ("Nothing is sent until you run it"). "Save and run with these inputs" saves the draft and runs it on this computer, then says, field by field, whether the output holds what the recording ended with. From the command line: reqlyn demonstrate a.har b.har --save "Device lookup" --check c.har --yes.
Recording a task
You can make the recordings in Reqlyn instead of saving HAR files from a browser.
- Record through a proxy… starts a recording proxy on a free port of this computer. Point a client at it and do the task. It shows its address, counts the requests kept, and holds them in memory only. HTTPS is carried through unread and counted, unless you make a recording authority. "Stop recording" ends it, and the recording joins the session's list.
- Read HTTPS too… makes a recording authority whose certificates are good only for the hosts you list, with its key in the secret store. "Trust it on this computer" adds it to the current user's trust on Windows (Windows asks you first); "Take it out of the trust" and "Remove it" undo that. While it is trusted, anything that trusts it trusts what it signs for those hosts, so remove it when you are done.
- Record in a browser… opens an inbox for the Reqlyn recorder, a Chromium extension in
extensions/chromiumloaded unpacked. The page shows the inbox's address and a pairing code; the extension records one tab and posts it when you stop. After five wrong codes the inbox hears no one.
Once there are two recordings, "Compare these N recordings" compares them; "Forget them" lets them go. Nothing of a recording is written to disk.
A mock from recordings or a description
"Serve as a mock…" takes HAR recordings, OpenAPI descriptions or both (see "From a description" below) and answers, on 127.0.0.1, what HAR recordings answered: a path asked as recorded gets its answers in turn, then its last; a path that only fits an endpoint's pattern gets that endpoint's first answer; anything else is a 404. Point an operation's base address at it to test with no upstream reached.
Its page has fields for faults, counted over every request: refuse every nth with 429, expire a token every nth (401), a delay in milliseconds, cut every nth body in half, and a page number that answers 500. "Restart with these choices" keeps the address. "Keep what is made" makes the mock stateful at the next restart, as --stateful does. It lists the last twenty requests it heard. "Stop the mock" ends it.
From the command line: reqlyn mock first.har second.har --port 9000 --throttle 5.
From a description
reqlyn mock inventory.yaml --stateful serves what an OpenAPI description says: each path and method answers its lowest success status, with the JSON media's example, else its first named example, else realistic data generated from its schema (through $ref, allOf merged, the first of oneOf, every property, a schema's own example kept): each value of its format (a date-time, a date, a UUID, an email address, an IPv4 or IPv6 address, a host name, an address), within its range, length and enum, and like its field's name (email, hostname, ip, city, country, status, price, createdAt and many more). Nothing generated is real: people and places are a fixed few, addresses are private or documentation ranges, and a field named as a secret is not-a-secret. The same call is answered the same each time, so a test against the mock can be kept as a case and replayed. With --plausible and Claude assistance on, the configured model is first asked for plausible, made-up values of the string fields Reqlyn has no words for (a rack, a serial), sent only their names and types, never a value or an example; what it suggests is used for those fields, and what was asked is printed first. Without it nothing is sent anywhere. The server's own path (https://host/api) comes before each path. Recordings and descriptions can be given together; a recorded answer comes first.
With --stateful, a POST of a JSON object is kept, given an id when it has none, and answered 201; a GET of the same path lists what was kept; a GET, PUT, PATCH or DELETE of the path and an id reads, replaces, changes (its id kept) or removes one, and a record that is not there is 404. Each such answer is printed with "(kept)". Anything else is left to the recorded and described answers.
Lint rules for a description
reqlyn lint <description> holds an OpenAPI or AsyncAPI description to a ruleset written as Spectral writes them, run by Reqlyn itself, offline. It uses the ruleset given with --ruleset, or .spectral.yaml, .spectral.yml or .spectral.json in the folder it runs in, or else Spectral's rules for what the description is: spectral:oas for OpenAPI, spectral:asyncapi for AsyncAPI. Each finding is printed with where it is (its path in the description), its severity, its rule and why; --json prints them as Spectral's JSON output does. It ends with 1 when a finding is an error, or at the severity --fail-severity names.
A ruleset's rules are read as Spectral reads them: given (a JSONPath, or an alias from aliases), then with field (a property, @key, or a JSONPath from the target) and one of Spectral's core functions (truthy, falsy, defined, undefined, pattern, length, enumeration, casing, alphabetical, xor, or, schema), severity (error, warn, info, hint, off), message with {{error}}, {{description}}, {{path}}, {{property}} and {{value}}, formats (oas2, oas3, oas3.0, oas3.1, asyncapi2, asyncapi3), and recommended. extends takes files beside the ruleset and spectral:oas or spectral:asyncapi, [spectral:oas, all] for every rule, [spectral:oas, off] for none until named; a rule of an extended set is turned off, or given another severity, by its name alone under rules. Not run, each refused with a sentence saying so: a ruleset extended from an address (download it beside yours), a ruleset or a function written in JavaScript, and JSONPath that only Spectral's JSONPath Plus reads (@property, @parent, script); the rest of JSONPath Plus's spellings (===, [get,put], $.x-team) are read as RFC 9535 JSONPath. A pattern is Rust's regular expression, without look-around.
spectral:oas holds Spectral's OpenAPI rules by their names, with Spectral's severities and the same ones on by default; its findings on a fixture are Spectral 6.17's. It leaves out the rules that hold the whole description, or its examples, to a JSON Schema (oas2-schema, oas3-schema, oas2-valid-*-example, oas3-valid-*-example, openapi-tags and oas3_2-no-deprecated-xml-attribute). spectral:asyncapi holds Spectral's AsyncAPI rules for 2.x and 3.x the same way, Spectral 6.17's findings on a 2.6 and a 3.0 fixture; it leaves out the rules that hold the document, a payload, a schema's default or examples, or a message's examples to a schema (asyncapi-schema, asyncapi-payload*, asyncapi-schema-default, asyncapi-schema-examples, asyncapi-message-examples, asyncapi-3-document-*), and asyncapi-3-operation-security, which needs the document's $refs followed.
reqlyn lint --operation <operation> holds an operation stored here, and the requests its steps send, to Reqlyn's own rules, reqlyn:operations, unless a ruleset is named or found: reqlyn-operation-name (it has a name of its own), reqlyn-operation-description and reqlyn-operation-owner (it says what it is for, and who answers for it), reqlyn-request-name (each request is named), reqlyn-credential-named (an error: a header whose name Reqlyn masks as a secret, such as Authorization, an API key, a token or a cookie, written into a request, or left masked there, rather than kept as a credential it names or a secret variable), and reqlyn-write-reads-first (a step that writes names a read of what it writes to first). An operation is read as a document of its own, reqlyn: operation with operation as it is kept and requests by id (each its name, method, url, headers, credential and description), so a ruleset of your own can hold it with given and then too, its rules given formats: [reqlyn].
The assistant
With Claude assistance on, the robot button in the title bar (or "Open or close the assistant" in the command palette) opens the assistant at the right of the screen. Ask it for what you want built: a request, an operation over saved requests, its inputs and output, a variable, a test, a case. It reads what is here as it needs (your saved requests with every secret header masked, a secret in an address or a body masked, your operations, the selected environment's variables without a secret's value) and proposes each change, which you keep or reject; nothing is kept until you keep it, and a kept change is listed at once where it belongs. A test of an operation that only reads runs as it asks, unless what it gives as the input could say where a request is sent; a test that writes, and every change, waits for you. It never writes a secret: a token, a key or a password is kept as a credential you name, or a secret variable, which it cannot set. What it is sent goes to the model Claude assistance names, and is said at the panel's head.
Asked to diagnose a failed test or case, it is told the operation, what failed and why, how each step ended, and what each step received, every secret-named value masked: all of it is the chat's first message, so you see what was sent. It says where it failed and proposes the fix, an output read from another path, for instance, which you keep or reject as any change. "Diagnose" under a failed test of a saved operation, or beside a case that does not hold, does this: the assistant's panel opens with the failure said.
Explain with Claude
Off unless you turn it on. In Settings, "Claude assistance" takes your own Anthropic API key, kept in the secret store, and a model (claude-sonnet-5-5 unless you choose another). Then a task from recordings offers "Explain with Claude…":
- It first shows exactly what would be sent: the task's shape only, meaning each call's method and path template, the names of query parameters, the names and kinds of fields, what flows where, and the inputs and output. No value and no host is ever in it.
- Nothing goes until you press "Send to Claude".
- The answer is shown as "Suggested by Claude, not applied": an explanation, and suggested names for the steps, inputs and output. Nothing is applied by itself, and nothing of the question or answer is kept.
Linked to a server whose workspace has assistance turned on, the question goes through the server with the workspace's key instead, and says so.
The mirror folder and Git
In Settings, a mirror folder gets a text file for each saved request and operation, named for its identifier, whenever it is saved. The files hold no secret values; they are what an export holds. Keep them with your own tools.
With a folder set, Settings shows GIT under it:
- "Start a Git repository here" when the folder is not one;
- otherwise the branch, how many files changed, and how far it is ahead of or behind its upstream;
- a field for the commit message, and Commit, Pull and Push.
Git is the git on your PATH, run with fixed arguments and your own configuration and credentials, never through a shell. Pull only fast-forwards: nothing is merged by itself.
A file changed outside Reqlyn, by a pull or by hand, is never overwritten and never applied by itself. It is listed under INCOMING: "changed", "new", or "changed here too" when you also changed it. "Compare" shows MINE · SAVED HERE beside THEIRS · IN THE FOLDER; "Take theirs" saves the file's version as the item's next revision, and "Keep mine" writes yours over the file.
Help for Reqlyn 0.5.1. All help topics