Proxy API

Importante

Desde la versión 3.3.1, cada solicitud de API de proxy de desarrollo requiere el Authorization: Bearer <token> encabezado; las solicitudes sin un token válido devuelven 401 Unauthorized.

El proxy de desarrollo incluye una API web que permite interactuar con el proxy mediante programación. La API está disponible en la dirección IP y el puerto especificados en la configuración del proxy.

Dev Proxy genera un token único para cada instancia en ejecución y lo almacena en un archivo al que solo se puede acceder al usuario que inició la instancia. Obtenga el token mediante devproxy status o devproxy api token. Cuando se establece la CI variable de entorno, use devproxy api token porque dev Proxy omite el token del estado y la salida de inicio.

Para usar un token conocido en lugar de uno generado, por ejemplo, cuando otra herramienta inicia Dev Proxy y llama a su API, establezca la DEV_PROXY_API_TOKEN variable de entorno antes de iniciar el proxy de desarrollo o pasarla mediante la --env opción . El valor debe tener al menos 32 caracteres, no contar relleno final = y solo puede contener letras ASCII, dígitos y los caracteres -, ~_+.y /, opcionalmente seguidos de = relleno. El proxy de desarrollo recorta los espacios en blanco circundantes. Si el valor no es válido, el proxy de desarrollo no se inicia y se cierra con un error. El proxy de desarrollo sigue almacenando el token, por lo que devproxy status, devproxy api tokeny devproxy stop siguen funcionando.

Incluya el token en el Authorization encabezado:

Authorization: Bearer <token>

Las solicitudes sin un token válido devuelven 401 Unauthorized. Las solicitudes del explorador también deben provenir de un origen enumerado en la apiAllowedOrigins configuración. Otros orígenes devuelven 403 Forbidden.

Operations

En la lista siguiente se muestran las operaciones de API disponibles.

GET /proxy

Devuelve una instancia de ProxyInfo con información sobre la instancia de Proxy de desarrollo que se está ejecutando actualmente.

Ejemplo: Obtención de información sobre la instancia de Proxy de desarrollo actualmente en ejecución

Solicitud:

GET http://localhost:8897/proxy
Authorization: Bearer <token>

Respuesta:

200 OK

{
  "recording": false,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

POST /proxy

Controla la instancia del proxy de desarrollo que se está ejecutando actualmente. Para iniciar y detener la grabación desde un script o una canalización de CI, consulte Registro desde scripts y CI.

Ejemplo: iniciar la grabación

Solicitud:

POST http://localhost:8897/proxy
Authorization: Bearer <token>
content-type: application/json

{
  "recording": true
}

Respuesta:

200 OK

{
  "recording": true,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

Ejemplo: detener la grabación

Solicitud:

POST http://localhost:8897/proxy
Authorization: Bearer <token>
content-type: application/json

{
  "recording": false
}

Respuesta:

200 OK

{
  "recording": false,
  "configFile": "/Users/user/dev-proxy/devproxyrc.json"
}

Detener la grabación y generar informes

Detener la grabación hace más que detener la captura de solicitudes. Cuando se envía {"recording": false} mientras el proxy de desarrollo está grabando, El proxy de desarrollo pasa las solicitudes grabadas a todos los complementos habilitados, en el orden en que aparecen en el archivo de configuración. Esto es lo mismo que presionar s en la consola donde se ejecuta el proxy de desarrollo. Durante este paso:

  • Los complementos de informes analizan las solicitudes grabadas y generan informes.
  • Los periodistas convierten los informes en archivos. Cada periodista escribe un archivo para cada informe, denominado <plugin>_<reporter>.<extension>, por ejemplo, ExecutionSummaryPlugin_MarkdownReporter.md. <plugin> es el nombre de la instancia del complemento que generó el informe y <reporter> es el nombre de la instancia del periodista. Si ya existe un archivo con ese nombre, el periodista anexa una marca de tiempo, por ejemplo, ExecutionSummaryPlugin_MarkdownReporter_20261105114500.md.
  • Los complementos de generador, como , OpenApiSpecGeneratorPluginescriben los archivos que generan.

Dev Proxy escribe estos archivos en su directorio de trabajo actual, que es el directorio desde el que inició el proxy de desarrollo.

La API responde después de que todos los complementos terminen de procesar las solicitudes grabadas. Dependiendo de los complementos que use, por ejemplo, complementos que llaman a un modelo de lenguaje, este paso puede tardar un tiempo, así que asegúrese de que el cliente HTTP no agote demasiado pronto el tiempo de espera. Cuando llegue la respuesta, los archivos de informe se escriben en el disco.

El proxy de desarrollo también registra el progreso del procesamiento de las solicitudes registradas:

Mensaje de registro Meaning
DONE Todos los complementos terminaron de procesar las solicitudes grabadas.
No requests to process Un complemento no encontró ninguna solicitud grabada para analizar.
An error occurred in a plugin Error en un complemento. Dev Proxy continúa con el siguiente complemento y registra DONE cuando finalizan todos los complementos.

Si el proxy de desarrollo no está grabando al enviar {"recording": false}, El proxy de desarrollo no procesa ninguna solicitud, no escribe ningún archivo y no registra DONE.

Tip

Si detiene el uso del proxy de desarrollo mientras POST /proxy/stopproxy está grabando, Dev Proxy también procesa las solicitudes grabadas antes de salir. Sin embargo, esa API responde inmediatamente, por lo que debe esperar a que el proceso de proxy de desarrollo salga para saber que los informes están listos. Para saber exactamente cuándo están listos los informes, detener la grabación primero, esperar la respuesta y, a continuación, detener el proxy de desarrollo.

Para obtener un script completo que inicia el proxy de desarrollo, controla la grabación a través de la API y espera a que el proxy de desarrollo finalice, consulte Uso del proxy de desarrollo en escenarios de CI/CD.

POST /proxy/jwtToken

Genera un token web JSON (JWT).

Solicitud:

POST http://localhost:8897/proxy/jwtToken
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Dev Proxy",
  "audiences": [
    "https://myserver.com"
  ],
  "issuer": "dev-proxy",
  "roles": [
    "admin"
  ],
  "scopes": [
    "Post.Read",
    "Post.Write"
  ],
  "claims": {
    "claim1": "value",
    "claim2": "value"
  },
  "validFor": 60
}

Nota:

Las notificaciones registradas (por ejemplo, iss, sub, audexp, , nbf, , iat) jtise agregan automáticamente al token. Si especifica alguna de estas notificaciones en la solicitud, la API omite los valores que proporcione.

Respuesta:

200 OK

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IkRldiBQcm94eSIsInN1YiI6IkRldiBQcm94eSIsImp0aSI6IjkyZjM5YzciLCJzY3AiOlsiUG9zdC5SZWFkIiwiUG9zdC5Xcml0ZSJdLCJyb2xlcyI6ImFkbWluIiwiY2xhaW0xIjoidmFsdWUiLCJjbGFpbTIiOiJ2YWx1ZSIsImF1ZCI6Imh0dHBzOi8vbXlzZXJ2ZXIuY29tIiwibmJmIjoxNzI3MTk4MjgyLCJleHAiOjE3MjcyMDE4ODIsImlhdCI6MTcyNzE5ODI4MiwiaXNzIjoiZGV2LXByb3h5In0.E_Gj9E58OrAh9uHgc-TW8DYfq8YHFrhaUTpKA4yXEIg"
}

GET /proxy/logs

Devuelve la salida del registro del proxy de desarrollo. Equivalente al logs comando . Este punto de conexión solo está disponible cuando el proxy de desarrollo se ejecuta en modo desasociado. De lo contrario, la API devuelve 404 Not Found.

Parámetro de consulta Descripción Predeterminado
lines Número de líneas que se van a devolver desde el final del registro 50
follow Cuando true, transmite nuevas líneas de registro como eventos enviados por el servidor false
since Devuelve solo las líneas registradas desde la fecha y hora especificadas. Use una duración (por ejemplo, 30s, 5m, 1h, 1d) o una fecha y hora ISO 8601 (por ejemplo, 2026-01-24T14:00:00 o 2026-01-24T14:00:00Z). Si la marca de tiempo no incluye un desplazamiento de zona horaria, Dev Proxy usa la zona horaria local. n/a

El since parámetro filtra las líneas de registro por su fecha y hora completas, tanto al devolver líneas de registro como al transmitirlas. El proxy de desarrollo filtra cada solicitud por la hora en que se inició, por lo que no se devuelve una solicitud que se inició antes de la hora especificada, incluso si finalizó más adelante.

De forma predeterminada, la API devuelve las líneas de registro como texto sin formato. Para obtener una matriz JSON de entradas de registro, establezca el Accept encabezado application/jsonen . Para transmitir líneas de registro como eventos enviados por el servidor, establezca el Accept encabezado en o establezca en followtrue.text/event-stream

Solicitud:

GET http://localhost:8897/proxy/logs?lines=10
Authorization: Bearer <token>

Respuesta:

200 OK
content-type: text/plain

[last 10 lines of the Dev Proxy log]

POST /proxy/mockrequest

Genera una solicitud ficticia. Equivalente a presionar w en la consola donde se ejecuta El proxy de desarrollo. La API responde una vez completada la solicitud simulada.

Solicitud:

POST http://localhost:8897/proxy/mockrequest
Authorization: Bearer <token>

Respuesta:

204 No Content

GET /proxy/rootCertificate?format=crt

Descarga la clave pública del certificado raíz en formato PEM (correo mejorado de privacidad) que el proxy de desarrollo usa para descifrar las solicitudes HTTPS. Esta API es útil cuando desea confiar en el certificado raíz en el host mientras ejecuta proxy de desarrollo en un contenedor de Docker.

En este momento, el único formato admitido es crt. La API devuelve un error de solicitud incorrecta 400 si especifica algún otro formato o no especifica un formato en absoluto.

Solicitud:

GET http://localhost:8897/proxy/rootCertificate?format=crt
Authorization: Bearer <token>

Respuesta:

content-type: application/x-x509-ca-cert

-----BEGIN CERTIFICATE-----
[base64 encoded certificate]
-----END CERTIFICATE-----

POST /proxy/stopproxy

Cierra correctamente el proxy de desarrollo. Si el proxy de desarrollo está grabando, detiene la grabación y genera informes antes de salir. La API responde inmediatamente antes de que el proxy de desarrollo termine de apagarse.

Solicitud:

POST http://localhost:8897/proxy/stopproxy
Authorization: Bearer <token>

Respuesta:

202 Accepted

Dev Proxy devuelve 202 Accepted tan pronto como se inicia el apagado. La respuesta no significa que el proxy de desarrollo se haya cerrado. Durante el apagado, proxy de desarrollo:

  1. Deja de aceptar nuevas solicitudes de proxy. Si dev Proxy está registrado como proxy del sistema, restaura la configuración anterior del proxy del sistema. El proxy de desarrollo espera hasta cinco segundos para que se cierren las conexiones abiertas y, a continuación, cierra las conexiones restantes.
  2. Detiene la grabación, si la grabación está activada y ejecuta los complementos de informes en las solicitudes grabadas, igual que al detener la grabación usted mismo. Cuando finalicen los complementos, Dev Proxy escribe los informes y registros DONE.
  3. Quita su información de instancia, por lo que devproxy statusdevproxy stop ya no la enumera.
  4. Sale con el código 0de salida .

El proxy de desarrollo no quita su certificado raíz del almacén de certificados de confianza al apagarse. Para quitar el certificado, use cert remove.

El apagado suele tardar unos segundos. Puede tardar más tiempo cuando los complementos de informes procesan una grabación grande. Después de que se inicie el apagado, la API ya no es accesible, por lo que no sondee la API para comprobar si el proxy de desarrollo ha salido. En su lugar, use una de estas opciones:

  • Espere a que se cierre el identificador de proceso (PID).devproxy --detach
  • Ejecute devproxy status --pid <pid> hasta que devuelva código 1de salida , lo que significa que la instancia ya no se está ejecutando. Para obtener más información, consulte estado.
  • Si estaba grabando, compruebe el registro del proxy de desarrollo para ver el DONE mensaje, qué registros del proxy de desarrollo después de que finalicen los complementos de informes. Para obtener un ejemplo, consulte Uso del proxy de desarrollo en escenarios de CI/CD.

Por ejemplo, para esperar a que una instancia de Dev Proxy desasociada salga en Linux o macOS:

# DEVPROXY_PID is the PID that devproxy --detach printed
# TOKEN is the API token from devproxy api token
curl -X POST http://localhost:8897/proxy/stopproxy -H "Authorization: Bearer $TOKEN"

while ./devproxy/devproxy status --pid $DEVPROXY_PID > /dev/null 2>&1; do
  sleep 1
done

Evite finalizar el proceso de proxy de desarrollo de forma forzada, por ejemplo, mediante kill -9. Al finalizar el proceso de esta manera, El proxy de desarrollo no vacía la configuración del proxy del sistema de grabación ni restauración. Para detener el proxy de desarrollo desde la línea de comandos, use stop, que llama a esta API y espera hasta 10 segundos para que el proxy de desarrollo salga.

Models

ProxyInfo

Información sobre la instancia del proxy de desarrollo que se está ejecutando actualmente.

Propiedad Tipo Descripción
recording boolean Si el proxy está grabando solicitudes actualmente
configFile string Ruta de acceso al archivo de configuración que usa el proxy de desarrollo (solo lectura)

JwtOptions

Opciones para generar un token JWT.

Propiedad Tipo Descripción
name string Nombre del usuario para el que se va a crear el token
audiences string[] Audiencias para las que se va a crear el token
issuer string Emisor del token
roles string[] Una notificación de rol que se va a agregar al token
scopes string[] Una notificación de ámbito que se va a agregar al token
claims KeyValuePair Notificaciones que se van a agregar al token
validFor number Duración (en minutos) para la que el token es válido
signingKey string Clave que se va a usar para firmar el token. Debe tener al menos 32 caracteres. Si no se especifica, usa una clave generada aleatoriamente.

JwtInfo

Información sobre un token JWT.

Propiedad Tipo Descripción
token string Token JWT

Consulte también