📄 Rext Specification (.rext)

Este repositorio contiene la definición oficial del lenguaje Rext, una evolución del formato .http diseñada para flujos de trabajo dinámicos y automatizados.

¿Qué hace a Rext diferente?

A diferencia de los archivos .http tradicionales, Rext introduce directivas inteligentes para manejar el ciclo de vida completo de una petición: captura de datos, validaciones, pre-ejecución, configuración compartida y reintentos.

---

Sintaxis Base

Cada request se separa con ###, ---, o una doble línea vacía. La primera línea indica el método y la URL.

###
GET https://api.example.com/users

---
POST https://api.example.com/users
Content-Type: application/json

{
  "name": "John",
  "email": "john@example.com"
}

@assert status == 201
@capture userId = body.id

Delimitadores

Delimitador	Descripción
###	Separador clásico (puede llevar texto después como comentario)
---	Separador limpio estilo Markdown
Doble línea vacía	Dos líneas vacías consecutivas separan requests implícitamente

Orden de una request: directivas → método + URL → headers → (línea vacía) → body → (línea vacía o @directive) → post-directivas (@assert, @capture)

Métodos soportados

GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

---

Directivas

@name — Nombre de la petición

@name Get Users
GET https://api.example.com/users

@id — Identificador único (6 caracteres alfanuméricos)

Se auto-genera al guardar si no está presente.

@id abc123
@name Login
POST https://api.example.com/auth/login

@collection — Agrupa peticiones en colecciones

@collection Auth API
@name Login
POST https://api.example.com/auth/login

@group — Sub-agrupación dentro de colecciones

Soporta niveles separados por /.

@collection Auth API
@group Users / Admin
@name Create Admin
POST https://api.example.com/admin/users

@tags — Etiquetas para filtrado

@tags auth, critical, v2
@name Login
POST https://api.example.com/auth/login

@deprecated — Marca una petición como obsoleta

@deprecated
@name Old Login
POST https://api.example.com/v1/login

@query — Query parameters

Define query parameters como directivas separadas de la URL. Los valores se codifican automáticamente con encodeURIComponent.

@name Search Users
GET {{baseUrl}}/users
@query page = 1
@query limit = 20
@query search = {{searchTerm}}
@query filter = "active users"

Equivale a: GET {{baseUrl}}/users?page=1&limit=20&search={{searchTerm}}&filter=active%20users

Soporta variables {{}} en los valores. Las comillas envolventes se eliminan automáticamente.

@body — Body desde archivo

Envía el contenido de un archivo como body de la petición.

@name Upload Data
POST {{baseUrl}}/import
Content-Type: application/json
@body ./data/payload.json

La ruta es relativa al archivo .rext.

---

Variables y Captura

Variables con {{}}

Reemplaza valores dinámicamente usando variables de sesión, colección, entorno o globales.

GET {{baseUrl}}/users
Authorization: Bearer {{token}}

@capture — Captura de datos de la respuesta

Extrae valores del response y los almacena en un scope.

Scopes: session (default), collection, env, global

@name Login
POST {{baseUrl}}/auth/login

@capture token = body.access_token
@capture env.userId = body.user.id
@capture collection.refreshToken = body.refresh_token
@capture global.apiVersion = body.version

Valores literales:

@capture session.status = "active"
@capture session.count = 42
@capture session.flag = true

---

Pre-Requests

@pre — Ejecuta peticiones previas

Referencia un @id para ejecutar esa petición antes de la actual. Los @capture de la pre-request setean variables disponibles para la request principal.

###
@id abc123
@name Login
POST {{baseUrl}}/auth/login
@capture env.token = body.access_token

###
@name Get Profile
@pre abc123
GET {{baseUrl}}/profile
Authorization: Bearer {{token}}

Múltiples @pre permitidos (ejecución secuencial):

@pre abc123
@pre def456
@name Full Flow
GET {{baseUrl}}/dashboard

Protección contra ciclos: si A tiene @pre B y B tiene @pre A, la cadena se detiene.

---

Assertions

@assert — Validaciones de respuesta

Valida condiciones sobre la respuesta. Si falla, se muestra ❌ en el panel de resultados.

Targets

Target	Descripción	Ejemplo
status	Código HTTP	@assert status == 200
body	Cuerpo (JSON path)	@assert body.success == true
header	Headers de respuesta	@assert header.content-type contains application/json
duration	Tiempo de respuesta (ms)	@assert duration < 2000
size	Tamaño de respuesta (bytes)	@assert size < 10240
cookie	Cookies del response	@assert cookie.sessionId exists

Operadores de Comparación

Operador	Descripción	Ejemplo
==	Igual a	@assert status == 200
!=	Diferente a	@assert status != 500
>	Mayor que	@assert body.items.length > 0
<	Menor que	@assert duration < 2000
>=	Mayor o igual	@assert status >= 200
<=	Menor o igual	@assert status <= 299
contains	Contiene texto	@assert body.name contains John

Operadores de Tipo y Existencia

Operador	Descripción	Ejemplo
exists	Existe (no null/undefined)	@assert body.token exists
!exists	No existe	@assert body.error !exists
isArray	Es un array	@assert body.data isArray
isNumber	Es numérico	@assert body.count isNumber
isNull	Es null	@assert body.deletedAt isNull
isUndefined	Es undefined	@assert body.debug isUndefined
isEmpty	Está vacío	@assert body.errors isEmpty

Ejemplo completo

###
@name Create User
POST {{baseUrl}}/users
Content-Type: application/json

{
  "name": "John",
  "email": "john@example.com"
}

@assert status == 201
@assert body.id exists
@assert body.name == John
@assert body.email contains @
@assert body.roles isArray
@assert header.content-type contains application/json
@assert duration < 3000
@assert size < 5120

---

Reintentos y Timeout

@retry — Reintentos automáticos

Reintenta en caso de error 5xx. Opcionalmente con delay.

@retry 3
@name Flaky Request
GET {{baseUrl}}/unstable-endpoint

@retry 5 delay 1000
@name Critical Request
POST {{baseUrl}}/payment

@timeout — Timeout de la petición (ms)

@timeout 5000
@name Slow Request
GET {{baseUrl}}/heavy-report

---

Configuración

@config — Configuración compartida

Define valores por defecto que se aplican a todas las peticiones de una colección o de todo el archivo.

Config de archivo (aplica a todo)

@config
baseUrl: https://api.example.com
timeout: 5000
retries: 2
headers:
  Content-Type: application/json
  Accept: application/json
assert:
  status == 200

Config por colección

@config
collection: Auth API
baseUrl: https://auth.example.com
headers:
  X-API-Key: {{apiKey}}

Herencia y Override

• baseUrl: se antepone a URLs relativas (que empiezan con /)
• headers: merge (request sobreescribe config)
• timeout / retries: se aplican si el request no los define
• assertions: se acumulan (config + request)

---

Archivos de Entorno

rext.env.json

Define variables por entorno en la raíz del proyecto.

{
  "Development": {
    "baseUrl": "http://localhost:3000",
    "apiKey": "dev-key-123"
  },
  "Production": {
    "baseUrl": "https://api.production.com",
    "apiKey": "prod-key-456"
  }
}

Cambia de entorno desde la barra de estado de VS Code o el sidebar.

---

Ejemplo Completo

@config
baseUrl: https://api.example.com
headers:
  Content-Type: application/json
assert:
  status >= 200

###
@id a1b2c3
@collection Auth
@name Login
POST /auth/login

{
  "email": "{{email}}",
  "password": "{{password}}"
}

@capture env.token = body.access_token
@assert status == 200
@assert body.token exists
@assert duration < 2000

###
@collection Auth
@name Get Profile
@pre a1b2c3
GET /profile
Authorization: Bearer {{token}}

@assert status == 200
@assert body.email exists
@assert body.roles isArray
@assert body.roles isEmpty !exists
@assert header.content-type contains json