Ion REST API Client

Ion REST API Client is a standalone, open-source desktop application for creating, organizing, and executing HTTP requests. It provides a lightweight workflow around file-backed Collections and independently managed Environments, without requiring a hosted backend, team account, or external API client.

The desktop application is built with React, TypeScript, Vite, and Tauri 2. It targets macOS, Windows, and Linux.

Features

• File-backed Collections with a searchable request tree.
• Service, domain, resource, and folder-based request organization.
• Request editing for GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, and other HTTP methods.
• URL templates with {{variable}} environment references and {parameter} path parameters.
• Query and path parameter editing, including active/inactive parameters.
• Header editing and JSON request body editing.
• Bearer authentication support.
• Environment switching without modifying Collection files.
• Secure secret variables stored in the operating system keyring.
• Masked secret and cookie values.
• Collection/environment import, export, reload, and native-folder editing.
• Cookie jars scoped to the active Collection and Environment.
• Response status, headers, formatted JSON, raw content, and duration.
• Equivalent curl generation with secret values masked.
• Request method color coding and destructive-request confirmation.
• Resizable sidebar and reusable shadcn-based UI components.

Requirements

Browser development mode

• Node.js 22 or later
• npm

Desktop development and packaging

• Node.js 22 or later
• Rust stable and Cargo
• Tauri system prerequisites for the target operating system

For macOS, install the Xcode Command Line Tools and Rust:

xcode-select --install
brew install rustup
rustup toolchain install stable
rustup default stable

If Homebrew is unavailable, install Rust with https://rustup.rs/.

Getting started

Install dependencies:

npm ci

Start the Vite application:

npm run dev

Start the Tauri desktop application:

npm run desktop:dev

The browser application is useful for development and read-only imports. Use the Tauri application when native filesystem writes, native HTTP behavior, or operating-system secure storage are required.

Common commands

Command	Purpose
npm run dev	Start the Vite development server
npm run desktop:dev	Start the Tauri desktop application
npm run build	Type-check and build the web application
npm test	Run the Vitest test suite
npm run desktop:build	Build platform installers with Tauri

Using the application

Collections

A Collection contains request definitions and request-facing metadata. It does not contain environment values, cookies, or secret material.

Collections can be:

• Imported from a directory.
• Imported from a ZIP archive.
• Opened as a native folder in the desktop application.
• Exported from browser mode.
• Reloaded after the source files change.

Opening a native folder enables edits to be written back to the individual request files and Collection manifest. Browser imports remain in memory until they are exported.

Environments

Environments are independent from Collections. Import one or more Environment JSON files, select the active Environment in the footer, and switch targets without changing request definitions.

Environment variables are referenced with double braces:

{{baseUrl}}/orders/{{orderId}}

Nested JSON variables use dotted names:

{{api.baseUrl}}

Unresolved variables are shown before execution and prevent sending until the request is fully resolved.

Secrets

Mark an Environment variable as secret to keep its value outside the shared Environment JSON. Secret values are stored in the native operating-system keyring when running as a desktop application. The key is scoped by:

• Collection ID
• Environment name
• Variable name

Secret values are never written to Collection files, Environment files, request previews, curl output, or exports. The UI displays masked values by default.

When native secure storage is unavailable, development builds may use the session fallback implemented by the application. This fallback is not a portable or durable secret store.

Requests and responses

Select a request from the sidebar, edit its method, URL, parameters, headers, authentication, or JSON body, then send it with the active Environment. Responses include the status code, headers, duration, and formatted or raw body views.

The curl action generates an equivalent command. Secret values remain masked in generated curl output.

Cookies received from responses are stored in a Cookie jar scoped to the active Collection and Environment. Cookie values are masked by default and can be edited, deleted, or cleared from the cookie manager.

Collection format

A Collection is a portable directory:

payments/
├── collection.json
├── requests/
│   └── payments/
│       └── orders/
│           └── list-orders.json
└── environments/
    └── local.json

The manifest identifies the Collection and maps stable request IDs to request files:

{
  "schemaVersion": "1.0",
  "id": "payments",
  "name": "Payments",
  "requests": [
    {
      "id": "list-orders",
      "file": "requests/payments/orders/list-orders.json"
    }
  ],
  "sections": [
    {
      "name": "Orders",
      "service": "payments",
      "domain": "orders"
    }
  ]
}

Request files contain the executable definition:

{
  "id": "list-orders",
  "name": "List orders",
  "service": "payments",
  "domain": "orders",
  "method": "GET",
  "path": "{{baseUrl}}/orders/{customerId}",
  "pathParameters": [
    {
      "name": "customerId",
      "required": false,
      "active": true,
      "value": "customer-123"
    }
  ],
  "body": {
    "type": "none"
  },
  "authentication": {
    "mode": "none"
  }
}

Environment files contain variables and non-sensitive metadata:

{
  "schemaVersion": "1.0",
  "name": "local",
  "stage": "local",
  "variables": {
    "baseUrl": "http://localhost:8080"
  }
}

See docs/public/collection-directory-structure.md for the complete schema, validation rules, and directory conventions.

Bruno conversion

The repository includes a standard-library Python converter for Bruno collections:

python3 scripts/bruno_to_collection.py \
  /path/to/bruno-collection \
  /path/to/output-collection

The converter handles HTTP requests, methods, URLs, headers, JSON bodies, assertions, documentation, environments, and dotted variables. It skips non-HTTP Bruno resources and executable scripts. Review converted requests when Bruno scripts affect authentication, headers, or safety checks.

Architecture

The application is organized into:

• src/app/ — shell composition, header, footer, dialogs, and workspace orchestration.
• src/components/ — reusable UI abstractions and shadcn primitives.
• src/modules/collection/ — Collection loading, persistence, sidebar, and request tree.
• src/modules/requests/ — request editor, execution, authentication, and request tabs.
• src/modules/environment/ — Environment editing and persistence.
• src/modules/cookies/ — cookie editor, table, and cookie state.
• src/modules/secrets/ — secure secret metadata and storage.
• src/modules/response/ — response presentation.
• src/modules/storage/ — file-backed and browser persistence.
• src-tauri/ — native filesystem, HTTP, keyring, and desktop integration.
• tests/ — domain, storage, execution, controller, cookie, and secret tests.

The domain model keeps Collections and Environments separate. Runtime resolution combines the active resources only when a request is executed.

Testing and CI

Run the same checks locally that CI runs:

npm ci
npm test
npm run build

GitHub Actions runs tests and the production build on pushes and pull requests. The release workflow packages draft Tauri releases for macOS, Windows, and Ubuntu Linux.

Building installers

Build desktop installers locally with:

npm run desktop:build

Tauri places generated artifacts under src-tauri/target/release/bundle/. The release workflow uses the Tauri GitHub Action and creates a draft release tagged as rest-client-v__VERSION__.

Keep the version in package.json and src-tauri/tauri.conf.json aligned when preparing a release.

Security and privacy

• No hosted backend or account is required.
• Collection files must not contain credentials or environment-specific secrets.
• Secret values are kept outside shareable Environment JSON.
• Secret and cookie values are masked in the UI by default.
• Generated curl output masks secret values.
• No arbitrary request scripts are executed.
• Only explicitly sent requests perform network activity.
• Do not store production credentials in shared Collections or Environments.

Current limitations

• JSON is the supported structured request body format.
• Bearer authentication is implemented; other authentication modes remain declarative or unsupported.
• Browser mode cannot write to arbitrary native folders.
• Secure keyring persistence requires the Tauri desktop application.
• Request execution history and cloud synchronization are not included.
• Bruno executable scripts are not converted.

Documentation

• Collection directory structure
• Distribution and packaging
• License

License

This project is licensed under the MIT License. See LICENSE.