# REST Client (`rest-client.env.json`) – Environment & Variable Guide

This document explains how to use **REST Client by Mao (VS Code extension)** with **environment-specific variables**, including **local vs server values**, how to **select environments**, and how to **define and use variables** across multiple request files.

---

## 1. What is `rest-client.env.json`

`rest-client.env.json` is a **workspace-level configuration file** used by REST Client to provide **environment-based variable replacement**.

It allows you to:

* Define **local / dev / prod** values once
* Reuse variables across **all `.http` / `.rest` files**
* Switch environments without editing request files

---

## 2. File location (important)

The file **must** be placed at the **root of your VS Code workspace**:

```
/project-root
  rest-client.env.json
  api/
    users.http
    auth.http
```

❌ Not supported:

* Subfolders
* Per-directory env files
* `.env` files

---

## 3. Basic structure

```json
{
  "dev": {
    "baseUrl": "http://localhost:3000",
    "token": "dev-token"
  },
  "prod": {
    "baseUrl": "https://api.example.com",
    "token": "prod-token"
  }
}
```

* Each **top-level key** is an environment name
* Each environment is a **key/value map**

---

## 4. Local vs Server environments (recommended pattern)

### Example

```json
{
  "local": {
    "baseUrl": "http://localhost:3000",
    "tenantId": "local-tenant",
    "authToken": "local-dev-token"
  },
  "server": {
    "baseUrl": "https://api.myapp.com",
    "tenantId": "prod-tenant",
    "authToken": "prod-token"
  }
}
```

This allows **one request file** to work everywhere:

```http
GET {{baseUrl}}/tenants/{{tenantId}}/users
Authorization: Bearer {{authToken}}
```

---

## 5. Selecting an environment

REST Client **does not auto-detect** environments.

### How to select

1. Open **any `.http` / `.rest` file**
2. Look at the **VS Code status bar** (bottom-right)
3. Click:

   ```
   REST Client: No Environment
   ```
4. Choose:

   * `local`
   * `dev`
   * `prod`

Once selected, **all requests use that environment**.

---

## 6. Using variables in requests

Variables are referenced using `{{variableName}}`.

### URL

```http
GET {{baseUrl}}/health
```

### Headers

```http
Authorization: Bearer {{authToken}}
```

### JSON body

```http
POST {{baseUrl}}/login
Content-Type: application/json

{
  "tenant": "{{tenantId}}"
}
```

---

## 7. Variable priority (override rules)

REST Client resolves variables in this order:

1. **Request variables** (from previous responses)
2. **File variables** (`@var = value`)
3. **Environment variables** (`rest-client.env.json`)
4. **System variables**

### Example override

```http
@baseUrl = http://localhost:9999

GET {{baseUrl}}/debug
```

This overrides the environment value **for that file only**.

---

## 8. File-level variables (per-file only)

You can define variables at the top of a request file:

```http
@limit = 10
@sort = desc

GET {{baseUrl}}/users?limit={{limit}}&sort={{sort}}
```

⚠️ These are **not shared** across files.

---

## 9. Using response values as variables

You can extract values from a previous request:

```http
# @name login
POST {{baseUrl}}/login
Content-Type: application/json

{
  "email": "test@test.com",
  "password": "secret"
}
```

```http
@authToken = {{login.response.body.token}}

GET {{baseUrl}}/profile
Authorization: Bearer {{authToken}}
```

---

## 10. Security considerations

* `rest-client.env.json` is **plain text**
* Do **not** commit secrets

### Recommended `.gitignore`

```
rest-client.env.json
```

Alternative:

* Commit a `rest-client.env.example.json`
* Keep real values local

---

## 11. Unsupported features (important)

❌ No `.env` support
❌ No imports/includes
❌ No per-folder environments
❌ No string functions or replacements
❌ No conditionals

Variables are **simple text substitutions only**.

---

## 12. Recommended project layout

```
/project-root
  rest-client.env.json
  api/
    auth.http
    users.http
    billing.http
```

* Keep requests environment-agnostic
* Switch environments via the status bar
* Never hardcode production URLs

---

## 13. Summary

* `rest-client.env.json` lives at the **workspace root**
* Environments are **manually selected** in VS Code
* Variables are shared across all request files
* File variables override environment variables

---

End of document