# .http files

> Bring requests written in .http or .rest files (VS Code REST Client, JetBrains HTTP Client) into Cloak Proxy's API client, export collections as .http files, and copy captured traffic as .http.

Source: https://docs.subcloak.com/cloak-proxy/api-client/http-files/

Added in Cloak Proxy 0.4.1.

Many developers keep requests in plain-text `.http` files next to their code, for VS Code's REST Client or JetBrains' HTTP Client. Cloak Proxy reads and writes the same format, so you can bring those requests into the API client, run them with scripts, tests and environments, and give them back to your editor.

```http
@baseUrl = https://api.example.com

### Orders / Create order
# @name createOrder
POST {{baseUrl}}/orders HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{"sku": "TEE-01", "qty": 2}
```

## Import a .http file

1. In the API client, click **Import** in the toolbar.
2. Click **Choose Files…** and pick one or more `.http` or `.rest` files, or paste the file's text into the sheet. You can also drop files on the window.
3. Click **Import**. The file becomes a collection named after it.

| In the file | Becomes |
|---|---|
| `@name = value` lines before a request | Collection variables, used as `{{name}}` |
| `###` | The start of a request. Text after it names the request |
| `### Folder / Name` | A request in a folder (nested for more `/`) |
| `# @name createOrder` | The request's name when `###` has no text |
| `#` and `//` lines before the request line | The request's docs |
| `METHOD URL HTTP/1.1` | Method and URL. Without a method, `GET`. Lines starting with `?` or `&` continue the URL |
| `Name: value` lines | Headers |
| The text after a blank line | The body. JSON, XML and text become a raw body by `Content-Type`; `x-www-form-urlencoded` becomes form fields |
| `X-Request-Type: GraphQL` | A GraphQL body: the query, then a blank line and the variables as JSON |
| `< ./body.json` | A file body |

Response handler scripts (`> {% … %}`, `> ./handler.js`) and `>> response.json` lines aren't imported: Cloak Proxy's scripts use the `pm` API instead. The collection's **Overview** lists what was left out, so you can add [tests](https://docs.subcloak.com/cloak-proxy/api-client/scripts-and-tests/) in each request's **Scripts** tab.

> **Tip:**
> Run a `.http` file directly in CI: `cloakctl collection run requests.http` treats it as a collection, with your environments and scripts. See [cloakctl](https://docs.subcloak.com/cloak-proxy/automation/cloakctl/).

## Export a collection as .http

Right-click a collection and choose **Export › .http File (REST Client, JetBrains)…**, or choose it from **More** in the collection's tab.

The file starts with the collection's variables (secret ones are left out and listed in a comment), then has one block per HTTP and GraphQL request:

- `### Folder / Name` and `# @name` with a camel-case name.
- The request's docs as comments.
- Its query parameters in the URL.
- Every header it sends, **including headers it inherits** from its folders and collection.
- Bearer, Basic and API key auth (its own or inherited) as headers, with `{{variables}}` left in place.
- The body. Form-data bodies aren't written, and the block says which fields they had.

Requests of other kinds (gRPC, WebSocket, MQTT…) are left out.

## Copy one request

- In the API client, right-click a request and choose **Copy as .http**.
- In the traffic list, right-click captured requests and choose **Copy as › .http (REST Client)**. Each becomes a block with its headers (without `Host` and `Content-Length`) and its decoded body. In the inspector's code view, choose **.http (REST Client)** in the language menu.

## Use from an AI assistant or the command line

| Tool or command | Does |
|---|---|
| `import_into_client` | Takes `.http` text or a `.http` / `.rest` path, as well as the other formats |
| `export_http_file` | Returns a collection (or one folder) as a `.http` file, or writes it to `path` |
| `cloakctl collection import FILE.http` | Adds the file to the workspace as a collection |
| `cloakctl collection export NAME --out FILE.http [--folder NAME]` | Writes a collection as a `.http` file |
| `cloakctl collection run FILE.http` | Runs the file's requests, Newman-style |

## Related

  - [Import and export](https://docs.subcloak.com/cloak-proxy/api-client/import-and-export/): Postman, OpenAPI, HAR, Insomnia and cURL.
  - [Variables and environments](https://docs.subcloak.com/cloak-proxy/api-client/variables-and-environments/): Environments built on a base, and .env files.
  - [Collections and requests](https://docs.subcloak.com/cloak-proxy/api-client/collections-and-requests/): Headers every request in a folder sends.