Usage Documentation

Goal

API Calls helps you exercise REST services without relying on a browser or external tools. It lets you craft HTTP requests, send them, inspect responses, and organise them into tabs, collections, and workspaces.

Requirements and Installation

• Official packages: download the latest release for Linux, macOS, or Windows from GitHub Releases.
• Arch Linux: available through the api-calls-bin package (AUR).
• Running from source:
  1. npm install
  2. npm run dev to launch the application in development mode.
  3. npm run build:<platform> to generate installers (linux/mac/win).

First Run

1. On launch, the default workspace opens with the side menu collapsed.
2. Click New Tab (the + icon or Ctrl/Cmd+T) to prepare a new request.
3. Choose the HTTP method, enter the URL, and add the required parameters or body.
4. Press Ctrl/Cmd+Enter or the Send button to execute the request.
5. Review the response at the bottom: status, duration, size, and body.

Interface at a Glance

• Optional top menu: quick access to actions, view, tools, and updates (toggle from Settings or Ctrl/Cmd+M).
• Side menu: tabs for Collections, Environments, History, Cookies, and Settings (switch via shortcuts).
• Side panel: displays the content of the selected section (collection tree, environments, etc.).
• Central tabs: request editor, header/body configuration, and response viewer. Tabs support drag-and-drop reordering.
• Bottom console: log of sent requests and debugging messages.

Building and Sending Requests

1. Method and URL: use the selectors for GET, POST, PUT, PATCH, DELETE, and more. You can also define custom methods for non-standard HTTP verbs. URLs auto-complete with environment variables when selected.
2. Query parameters: add rows in the Params section.
3. Path parameters: define dynamic URL segments using :paramName syntax (e.g., /users/:id/posts/:postId). Values can be set in the Path section.
4. Headers: add request headers. They will overwrite collection headers.
5. Body: choose the mode (JSON, YAML, text, form-data, x-www-form-urlencoded, file). The Monaco-based editor offers syntax highlighting.
6. Authentication: configure authentication from the Auth tab:
   • Bearer Token: adds an Authorization header with your token.
   • Basic Auth: encodes username and password in the Authorization header.
   • OAuth 2.0: supports the Authorization Code flow. Configure your client ID, client secret, authorization URL, and token URL. The app opens an integrated browser window to complete the OAuth flow and automatically retrieves the access token.
   • Custom Token: add any custom header for authentication.
7. Environment: assign variables via Environment (collections can specify a preferred environment).
8. Send and cancel: Ctrl/Cmd+Enter sends the request, Esc cancels it.

Scripting

You can write JavaScript code to execute before a request is sent (Pre-request Script) or after a response is received (Post-request Script). Scripts run in a secure sandbox with a 60-second timeout limit.

Available Resources

• console: Use console.log(message) or console.error(message). Output appears in the bottom console.
• environment: access and modify environment variables.
  • environment.get(key) - retrieve a variable value
  • environment.set(key, value) - set or update a variable
  • environment.unset(key) - remove a variable
• http: Make asynchronous HTTP requests directly from your script.
  • await http.get(url, headers)
  • await http.post(url, body, headers)
  • await http.put(url, body, headers)
  • await http.delete(url, headers)
  • await http.request(method, url, body, headers) - for any HTTP method
• request: Access the current request details (method, URL, body, headers, queryParams).
• response (Post-script only): Access the received response (status, headers, body, rawBody).

Script Examples

// Fetch a token before sending the request
const res = await http.post('https://api.example.com/auth', {
  username: environment.get('user'),
  password: environment.get('pass')
});
environment.set('token', res.body.access_token);
console.log('Token refreshed');

// Check response status and extract data
if (response.status === 200) {
  const data = JSON.parse(response.body);
  environment.set('userId', data.id);
  console.log('User ID saved:', data.id);
} else {
  console.error('Request failed:', response.status);
}

Managing Tabs

• Duplicate: right-click a tab and choose Duplicate tab.
• Restore: Ctrl/Cmd+Shift+T reopens the last closed tab.
• Move: drag tabs to reorder them.
• Search: open the tab switcher with Ctrl/Cmd+O to find a tab by name.
• Close: Ctrl/Cmd+W closes the active tab.
• Bulk close: right-click for Close others or Close all.
• Save a request: Ctrl/Cmd+S saves to the linked collection.

Collections

• Create folders and sub-folders to group related requests.
• Assigning an environment to a collection propagates default variables to linked tabs.
• Use Pre-request Script and Post-request Script at the collection level to run JavaScript for all requests in the collection.
• Define collection headers that will be sent on all requests within the collection.
• Import and export from the context menu:
  • Postman v2.1.0: full compatibility with Postman collections.
  • OpenAPI 3.0.1: import API specifications and export your collections.
  • JSON/YAML: custom API Calls format for backup and sharing.
  • cURL: import cURL commands directly or export requests as cURL commands for sharing or terminal use.

Environments and Variables

• Define environments (dev, staging, prod) with key/value pairs.
  • Insert variables as {{variable}} in URLs, headers, or bodies.
  • Define environment headers that will be sent on requests.
• Duplicate, reorder, or export complete environments as needed.
• Pick the active environment per tab from the request toolbar.

Header Priority

Headers can be defined at multiple levels. When the same header is defined in different places, higher priority levels override lower ones:

1. Default headers (Settings) - lowest priority
2. Workspace headers
3. Environment headers
4. Collection headers
5. Request headers - highest priority

For example, if you set Content-Type: application/xml at the collection level but Content-Type: application/json at the request level, the request will use application/json.

History and Cookies

• History: stores up to maxHistory requests. Reopen entries as tabs or clear them in bulk.
• Cookies: when Manage cookies is enabled, stored cookies are listed and can be cleared per domain.

Workspaces

• Separate collections, environments, tabs, and cookies per project.
• Access the list and workspace actions from the side menu.
• Create, duplicate, rename, and remove workspaces. Each workspace is stored in its own file.

Settings

• Appearance:
  • Theme selection (Auto, Light, Dark, High Contrast, or custom themes).
  • Window mode: choose between custom or native title bar (Linux/Windows).
  • Request view orientation: horizontal or vertical layout.
• Behavior:
  • Menu visibility toggle.
  • Auto-scroll to active tab.
  • Notifications and confirmation prompts.
  • Save last response toggle.
• Network:
  • Request timeout: default is 30 seconds, adjust for slow APIs.
  • Follow redirects: automatically follow HTTP redirects.
  • Reject unauthorized: disable to allow self-signed SSL certificates (useful for local development).
  • Proxy configuration: route requests through an HTTP/HTTPS proxy for debugging or accessing internal networks.
• Default headers: define headers that apply automatically to all requests (lowest priority in the header hierarchy).

Auto Updates (Beta)

• On macOS and Windows, the app checks for updates in the background.
• On Linux, install new versions manually.

Essential Shortcuts

Tips and Troubleshooting

• If an HTTPS call fails, temporarily disable Reject unauthorized in Settings.
• Check the bottom console for validation messages.
• Use Restore tab to recover accidentally closed tabs.

Where Data Lives

Collections, environments, tabs, and cookies are stored per workspace under Electron's user data directory.

No telemetry: API Calls does not collect or send any data to external servers. All your data stays on your machine.

Additional Resources

• GitHub repository
• Issues: use Help > Submit bug or open a GitHub ticket.