Skip to content

OpenCollection

OpenCollection is an open specification for API collections — designed for portability between tools, version control, and CI. Restura uses it as its native format for export.

Postman’s format is locked. Insomnia’s is locked. Bruno’s is its own. Switching tools means a lossy migration every time. OpenCollection exists to be the format you can move into and out of without losing fidelity.

  • Request-shaped protocols Restura can save and run: HTTP, GraphQL, gRPC, SSE, and MCP (SSE / MCP ride along as x-restura-* extensions — see Restura extensions).
  • WebSocket and Socket.IO connections (#1209): a WebSocket item is the spec’s native websocket item (URL, headers, message or message variants), with Restura-only fields in x-restura-websocket; Socket.IO rides in x-restura-socketio. Neither is run by the collection runner or the CLI — see Restura extensions.
  • Kafka and MQTT connection presets (desktop): broker connection plus the produce / consume or publish / subscribe drafts, carried in x-restura-kafka / x-restura-mqtt. Credentials are never part of a preset — see Restura extensions.
  • Nested folders with inherited auth, scripts, and variables (folder request.variables; variables marked Keep local are never written). Folder-level default headers in the spec aren’t mapped yet.
  • Environments with scoped variables.
  • Scripts (pre-request and test) — sandbox-portable JavaScript.
  • Workflows — separately stored OWS orchestration artifacts that reference saved HTTP requests. The currently executable profile is deliberately bounded; see the workflow guide.
  • Auth schemes — Basic, Bearer, API key, OAuth 2.0, AWS SigV4, Digest, OAuth 1.0a, NTLM, and WSSE, at request, folder and collection level. Secrets held as SecretRef handles export value-less ({{handle:label}}), never as plaintext. NTLM round-trips and is sent by the desktop app only (#1069); Digest is applied after the server’s 401 challenge.
  • Vendor extensions via the extensions field — so tools can persist proprietary data while staying spec-compliant.
  • Bundled YAML — a single .yml / .yaml file. Easy to drop into another tool.
  • Directory layout — one file per request, in a folder structure that mirrors your collection tree. Friendly for git.

Restura exports the bundled YAML everywhere and the directory layout on desktop (via Save to Files / Sync to Disk); import auto-detects either.

Exporting a collection and importing it back into Restura preserves HTTP, GraphQL, gRPC, SSE, and MCP requests — including their auth, scripts, and folder placement — Kafka and MQTT connection presets (everything except credentials, which never leave the machine), WebSocket and Socket.IO connections, plus collection- and folder-level auth, scripts, and variables. A round-trip test exports a fully-populated request of each type and checks every field comes back; a new request field can’t be added without either carrying it or listing it as a known gap.

Known gaps — these are not preserved yet:

  • HTTP per-request settings (timeout, redirects, TLS verification) and the contract link (contractRef). The HTTP version preference is the exception: it round-trips through x-restura-http.
  • The secret marker on individual headers (the header value itself is exported).
  • OAuth 1.0a signature methods Restura can’t sign with (RSA-*, HMAC-SHA512) import as the signer default; the original value survives only while the imported item is unedited.
  • A WebSocket item’s OpenCollection auth block (Restura has no WebSocket auth): it survives only while the imported item is unedited. An xml message imports as text.

HTTP methods round-trip as written, including extension methods such as PROPFIND or QUERY (case preserved). An imported request whose method is invalid or refused (CONNECT, TRACE, TRACK) becomes GET, and Restura shows a warning naming the request.

Importing a Postman v2.1 collection into Restura and exporting as OpenCollection keeps the fields Restura models; round-tripping back to Postman is best-effort (some Restura-specific features have no Postman equivalent).

The OpenCollection v1.0.0 JSON Schema has no item type for SSE, MCP, Kafka, MQTT or Socket.IO, and its request, folder and auth objects reject unknown keys. Restura therefore keeps what the schema can’t hold in the document’s free-form root extensions field instead of adding non-schema keys to items or auth blocks (which the VS Code extension’s schema validation would flag):

ExtensionCarries
x-restura-sse, x-restura-mcpSSE / MCP requests (all fields). A folderPath (ancestor folder names) records the folder an item lives in; entries without one load at the collection root. An MCP request stores one operation: defaultMethod (e.g. tools/call) plus defaultParams.
x-restura-kafka, x-restura-mqttKafka / MQTT connection presets, placed with a folderPath like SSE / MCP. A Kafka entry holds connection (bootstrap brokers, client id, security protocol, SASL mechanism + username, TLS file paths, Schema Registry URL + username, acks, compression, idempotence, transactional id), produce (topic, key, payload template, encodings, headers, partition) and consume (group id, topics, start mode). An MQTT entry holds connection (broker URL, protocol version, client id, keepalive, clean start, timeouts, username, TLS file paths, last will, session expiry), the publish / subscribe drafts and saved publish templates (incl. MQTT 5 user properties). No passwords, OAuth tokens or key passphrases are ever written — they stay in the desktop’s encrypted store, so a teammate (or the same machine after a re-import) re-enters them. Values may contain {{var}} references, resolved when you connect or send.
x-restura-websocketRestura-only fields of native websocket items, matched by path (plus index when names repeat): protocols (subprotocols), options (auto-reconnect, attempts, delay, heartbeat interval / message, permessage-deflate), frameAssertion, and the composer draft (message) when the item also has saved messages. Saved messages are the native item’s message variants (title + message); a hex message is written as binary.
x-restura-socketioSocket.IO connections, placed with a folderPath like SSE / MCP: url, namespace, path, handshake auth, query and headers rows, authMode / authJson (JSON handshake auth), transports, subscribedEvents, the emit draft, saved emit templates and options (reconnect incl. reconnectionDelayMax / randomizationFactor, timeout, forceNew (kept for compatibility; every connect uses a fresh Manager), and the emit modifiers volatile / compress / ackTimeoutMs). Entries from older, hand-written files that used { key: value } maps for auth / query still import, and are written back in the row form. Header / query / handshake-auth values are written as stored; with secrets excluded, credential-named rows, URL credentials and every literal handshake-auth value (in authJson, every literal leaf) are blanked.
x-restura-grpcgRPC schema snapshots (reflected descriptors or an uploaded .proto), stored once per content hash (schemas), plus per-request timeout and schemaFetchedAt (when the snapshot was captured). requests entries reference a snapshot by hash and are matched to items by path (folder names + request name).
x-restura-graphqlGraphQL schemas loaded by hand (SDL file, pasted SDL or introspection JSON — stored as SDL), stored once per hash of the SDL (schemas). requests entries reference a schema by hash, carry its provenance (source, fileName, importedAt), the request’s subscription wire protocol (subscriptionProtocol) and the selected operationName of a multi-operation document — in any combination — and are matched to items by path (plus index among same-path HTTP requests when names repeat).
x-restura-authAuth options the schema’s auth objects lack: OAuth 1.0a addParamsToBody, NTLM workstation, WSSE passwordType. Each entry names its target (collection, folder or request), path and auth type, and only applies to a node whose auth has that type.
x-restura-httpPer-request HTTP settings the schema can’t hold. Today that is only the desktop HTTP version preference (httpVersion: http1.1, http2 or h2c-prior-knowledge; auto isn’t written). Entries are matched by path. Import sets only the HTTP version; the request’s other settings keep following your workspace defaults.
x-restura-contractThe collection’s linked API contract.

Other tools ignore these keys; Restura rebuilds them on every export and keeps unknown x-* keys from an imported file.