Cómo consumir una API REST desde PowerShell: guía práctica con ejemplos paso a paso

Introducción

Consumir una API REST desde PowerShell permite consultar servicios, intercambiar información y reducir tareas repetitivas sin desarrollar una aplicación completa. Con unas pocas instrucciones es posible enviar peticiones HTTP, interpretar respuestas JSON y crear procesos de automatización útiles para la administración de sistemas y el trabajo diario.

Imagina que necesitas consultar el estado de varias operaciones, recuperar un inventario o descargar datos para preparar un informe. En lugar de abrir una aplicación, buscar cada registro y copiarlo manualmente, puedes solicitar los datos a la interfaz que el sistema ofrece y procesarlos como objetos de PowerShell.

Esta guía se centra en cómo realizar esas llamadas desde PowerShell: preparar el entorno, ejecutar solicitudes GET, enviar JSON mediante POST, trabajar con encabezados y credenciales, gestionar fallos y construir un pequeño script de consulta. Los ejemplos de lectura y escritura emplean un servicio público de pruebas con datos ficticios; ninguna operación del laboratorio modifica un sistema empresarial real.

Índice

Qué necesitas para consumir una API REST desde PowerShell

Para empezar basta con tener PowerShell, conectividad con el servidor remoto y una dirección URL que represente un recurso accesible. No necesitas instalar bibliotecas de terceros para los ejemplos básicos: Invoke-RestMethod, Invoke-WebRequest, ConvertTo-Json y ConvertFrom-Json forman parte del entorno.

Conviene distinguir dos familias que todavía conviven en equipos profesionales:

• Windows PowerShell 5.1: habitual en muchas instalaciones de Windows. Permite ejecutar las peticiones esenciales de esta guía, aunque carece de parámetros incorporados en versiones posteriores.
• PowerShell 7 y posteriores: versión moderna, multiplataforma y recomendable para nuevos scripts cuando el entorno lo permita. Ofrece opciones adicionales para inspeccionar respuestas y gestionar determinados errores HTTP.

Comprueba tu versión antes de copiar ejemplos:

$PSVersionTable.PSVersion

# Ver la versión principal
$PSVersionTable.PSVersion.Major

Los ejemplos principales usan parámetros disponibles tanto en Windows PowerShell 5.1 como en PowerShell 7. Cuando aparezca una opción específica de PowerShell 7 se indicará expresamente. Ejecuta las pruebas con una cuenta ordinaria: consultar una API no requiere abrir la consola como administrador.

Qué sucede cuando PowerShell llama a una API REST

Una API REST expone recursos a través de direcciones y métodos HTTP. El cliente envía una solicitud y el servidor devuelve una respuesta formada, entre otros elementos, por un código de estado, encabezados y, cuando corresponde, un cuerpo. En muchos servicios corporativos, ese cuerpo utiliza JSON.

Antes de escribir código, identifica cuatro elementos:

• URL del recurso: por ejemplo, una colección de pedidos o un pedido concreto.
• Método: GET para consultar; POST para enviar una creación o una operación definida por el proveedor; PUT y PATCH para modificaciones; DELETE para solicitar una eliminación.
• Autorización y encabezados: credenciales y condiciones de intercambio exigidas por el servicio, si las hay.
• Contrato de respuesta: campos, tipos, errores, paginación y significado de los datos devueltos.

No todas las API interpretan estos métodos de manera idéntica. Su documentación es la referencia para saber qué campos admite, qué permisos necesita y qué efectos tiene una llamada. Aquí vamos a practicar con JSONPlaceholder, un servicio público que simula recursos como publicaciones y usuarios. Permite ensayar operaciones de escritura, pero no persiste realmente esos cambios.

Tu primera petición GET con Invoke-RestMethod

El comando más directo para consumir una API que devuelve JSON es Invoke-RestMethod. Recupera la respuesta y, cuando el formato es reconocible, transforma el JSON en objetos utilizables desde PowerShell.

Consultar un recurso concreto

$uri = 'https://jsonplaceholder.typicode.com/posts/1'

$post = Invoke-RestMethod -Uri $uri -Method Get

$post
$post.id
$post.title
$post.userId

La respuesta contiene propiedades como userId, id, title y body. Por eso puedes usar $post.title directamente, sin buscar texto dentro de una cadena JSON. Esta diferencia es especialmente útil al crear informes o automatizar comprobaciones.

Consultar una colección de registros

$posts = Invoke-RestMethod -Uri 'https://jsonplaceholder.typicode.com/posts' -Method Get

$posts.Count
$posts | Select-Object -First 5 id, userId, title

En una API real, la colección podría representar clientes, equipos, tickets o existencias. Es importante no asumir que la primera respuesta incluye todos los registros: algunos servicios devuelven páginas limitadas o una propiedad que contiene los elementos.

Cómo filtrar los resultados y pasar parámetros a una API

Hay dos lugares diferentes donde aplicar un filtro. Si el servidor admite parámetros de consulta, puedes pedirle únicamente la información que necesitas. Si ya has recibido los datos, puedes filtrarlos localmente con comandos de PowerShell.

Filtrar en el servidor mediante la URL

JSONPlaceholder permite solicitar las publicaciones de un usuario determinado:

$uri = 'https://jsonplaceholder.typicode.com/posts?userId=1'
$postsUsuario = Invoke-RestMethod -Uri $uri -Method Get

$postsUsuario | Select-Object id, title

El parámetro userId=1 forma parte de la URL; PowerShell no lo interpreta por sí mismo. Es el servicio el que decide si lo admite y cómo lo aplica. Para valores procedentes de variables, codifica los parámetros cuando sea necesario:

$textoBusqueda = 'informe mensual'
$textoSeguro = [uri]::EscapeDataString($textoBusqueda)

# Ejemplo de formato de URL; depende del contrato del proveedor
$uri = "https://api.ejemplo.com/v1/documentos?buscar=$textoSeguro"

api.ejemplo.com es una dirección ficticia: el fragmento anterior ilustra la construcción de una URL, no constituye una consulta ejecutable.

Filtrar después de recibir la respuesta

$posts = Invoke-RestMethod -Uri 'https://jsonplaceholder.typicode.com/posts' -Method Get

$seleccion = $posts |
    Where-Object { $_.userId -eq 1 } |
    Select-Object id, title

$seleccion | Format-Table -AutoSize

El filtrado local es útil cuando ya necesitas el conjunto completo, pero puede desperdiciar tráfico si el servidor ofrece una búsqueda equivalente. También conviene evitar Format-Table antes de exportar: ese comando está destinado a mostrar información en pantalla, no a preparar registros estructurados.

Invoke-RestMethod o Invoke-WebRequest: cuál utilizar

PowerShell dispone de dos comandos habituales para trabajar con servicios HTTP. Se parecen, pero no persiguen exactamente lo mismo.

Por ejemplo, con Invoke-WebRequest puedes inspeccionar el código de estado y el contenido recibido. El modificador -UseBasicParsing resulta especialmente apropiado en Windows PowerShell 5.1 y se acepta por compatibilidad en PowerShell 7:

$respuesta = Invoke-WebRequest `
    -Uri 'https://jsonplaceholder.typicode.com/posts/1' `
    -Method Get `
    -UseBasicParsing

$respuesta.StatusCode
$respuesta.Headers['Content-Type']
$respuesta.Content

Si necesitas analizar ese contenido como JSON de manera explícita:

$objeto = $respuesta.Content | ConvertFrom-Json
$objeto.title

En un flujo de trabajo ordinario, utiliza Invoke-RestMethod para los datos y recurre a Invoke-WebRequest cuando necesites examinar propiedades de la respuesta HTTP. No interpretes un estado 200 como garantía de que los valores de negocio son correctos: también hay que verificar el contenido esperado.

Enviar un objeto JSON a una API con POST

Consultar información no es lo mismo que crearla o modificarla. Cuando una API permite enviar datos mediante POST, lo habitual es construir el contenido en PowerShell, convertirlo a JSON y especificar su tipo.

Crear el cuerpo de la petición

$datos = @{
    title  = 'Prueba desde PowerShell'
    body   = 'Registro ficticio para practicar una API REST'
    userId = 1
}

$json = $datos | ConvertTo-Json
$json

El resultado es una cadena JSON válida para este recurso. Cuando existen objetos anidados, arrays o estructuras de mayor complejidad, revisa el parámetro -Depth de ConvertTo-Json para evitar que una serialización demasiado superficial altere el contenido.

Enviar la solicitud al servicio de pruebas

$respuesta = Invoke-RestMethod `
    -Uri 'https://jsonplaceholder.typicode.com/posts' `
    -Method Post `
    -ContentType 'application/json; charset=utf-8' `
    -Body $json

$respuesta | Select-Object id, title, userId

El servicio suele devolver un objeto que simula el registro creado, con un identificador asignado. Es un resultado de prueba: JSONPlaceholder no almacena definitivamente esa creación. En un sistema real, una respuesta de éxito puede indicar una operación aceptada, un recurso creado o un trabajo pendiente; hay que seguir el contrato del proveedor.

No envíes una tabla hash directamente suponiendo que PowerShell la convertirá siempre en JSON: según el método y los parámetros, el cliente puede tratarla como datos de formulario. La combinación ConvertTo-Json + -Body + -ContentType hace explícito lo que se transmite.

PUT, PATCH y DELETE: modificar recursos con precaución

Los métodos de escritura no son intercambiables. De forma general, PUT se emplea para reemplazar o establecer la representación de un recurso, PATCH para aplicar una modificación parcial y DELETE para solicitar su eliminación. Su semántica exacta y sus consecuencias dependen de cada API.

Esta petición PATCH es demostrativa y se realiza únicamente contra el servicio ficticio:

$cambio = @{ title = 'Título de demostración' } | ConvertTo-Json

$resultado = Invoke-RestMethod `
    -Uri 'https://jsonplaceholder.typicode.com/posts/1' `
    -Method Patch `
    -ContentType 'application/json; charset=utf-8' `
    -Body $cambio

$resultado.title

En un entorno de trabajo, comprueba antes si la operación es reversible, qué identificador apunta al registro correcto, qué permisos tiene la credencial y si un segundo envío provocaría duplicados. No ejecutes operaciones de modificación o borrado sobre datos reales hasta disponer de autorización, entorno de pruebas y una forma de verificar el efecto.

Una solicitud repetida después de un fallo de red merece especial atención. Si el servidor procesó el cambio pero la respuesta se perdió, el cliente no puede concluir automáticamente que nada sucedió. Los mecanismos de idempotencia o consulta posterior deben venir respaldados por la API; no se improvisan repitiendo cualquier POST.

Cómo enviar encabezados y autenticarse de forma segura

Muchas API corporativas exigen identificar al consumidor. Algunas utilizan una clave incluida en un encabezado; otras trabajan con un token Bearer o con flujos de identidad más elaborados. En todos los casos, debes seguir el mecanismo documentado por el proveedor.

Ejemplo de token Bearer

El siguiente bloque muestra la estructura de una solicitud a un servicio ficticio. Primero comprueba que existe el token y después lo envía en el encabezado Authorization:

$token = $env:API_TOKEN

if ([string]::IsNullOrWhiteSpace($token)) {
    throw 'Falta la variable de entorno API_TOKEN.'
}

$headers = @{
    Authorization = "Bearer $token"
    Accept        = 'application/json'
}

$datos = Invoke-RestMethod `
    -Uri 'https://api.ejemplo.com/v1/informes' `
    -Method Get `
    -Headers $headers `
    -TimeoutSec 20 `
    -ErrorAction Stop

La variable API_TOKEN debe configurarse por un medio autorizado antes de ejecutar el script. Separarla del código evita incrustarla directamente en el archivo, pero una variable de entorno no equivale por sí sola a un almacén seguro de secretos. En equipos compartidos o automatizaciones empresariales, utiliza el sistema de credenciales previsto por tu organización y limita quién puede leerlas.

Ejemplo de API Key

$apiKey = $env:API_KEY

if ([string]::IsNullOrWhiteSpace($apiKey)) {
    throw 'Falta la variable de entorno API_KEY.'
}

$headers = @{
    'X-API-Key' = $apiKey
    Accept      = 'application/json'
}

# Enviar $headers con -Headers al endpoint autorizado.

X-API-Key es solo un nombre habitual: otro proveedor puede exigir Authorization, un encabezado distinto o una combinación de credenciales. No publiques claves, no las incluyas en capturas y no registres encabezados completos que puedan contenerlas. Evita también introducir secretos en parámetros de consulta de una URL, salvo obligación explícita del proveedor y con los controles adecuados.

Utiliza siempre HTTPS para enviar credenciales y mantén activa la validación de certificados. Si falla una conexión TLS, investiga el certificado, la cadena de confianza y la configuración de red; desactivar la comprobación no convierte una integración insegura en una solución válida.

Cómo gestionar errores HTTP, tiempos de espera y respuestas inesperadas

Los ejemplos mínimos ayudan a entender la sintaxis, pero un script profesional debe distinguir entre una petición correcta, un fallo de transporte, un rechazo del servidor y una respuesta que llega sin los datos esperados.

Capturar un error sin ocultar su causa

$uri = 'https://jsonplaceholder.typicode.com/posts/999999'

try {
    $post = Invoke-RestMethod `
        -Uri $uri `
        -Method Get `
        -TimeoutSec 20 `
        -ErrorAction Stop

    if ($null -eq $post -or $null -eq $post.id) {
        throw 'La respuesta no contiene un registro válido.'
    }

    "Registro recibido: $($post.id)"
}
catch {
    $codigo = $null

    if ($null -ne $_.Exception.Response) {
        $codigo = [int]$_.Exception.Response.StatusCode
    }

    if ($null -ne $codigo) {
        Write-Warning "La consulta falló con HTTP $codigo."
    }
    else {
        Write-Warning 'La consulta falló antes de obtener una respuesta HTTP utilizable.'
    }
}

La ruta de ejemplo puede devolver 404 y activar el bloque catch. El código ilustra una captura básica compatible con ambos entornos; para un sistema real conviene conservar un registro técnico controlado, sin exponer tokens, datos personales ni contenido sensible. No conviertas todos los errores en una respuesta aparentemente vacía: un resultado vacío y una petición fallida significan cosas distintas.

Interpretar los códigos más habituales

En PowerShell 7 puedes utilizar opciones como -SkipHttpErrorCheck para inspeccionar respuestas HTTP de error sin convertirlas automáticamente en excepciones, o -StatusCodeVariable para recuperar el estado. Esos parámetros no están disponibles en Windows PowerShell 5.1, por lo que no deben incluirse sin verificar la versión.

Un código 429 no autoriza a reintentar inmediatamente en bucle. Respeta la política del proveedor y, si existe, el encabezado Retry-After. Para profundizar sin desviar esta guía hacia otra materia, consulta cómo detectar errores habituales al consumir APIs y cómo controlar límites de uso y cuotas de una API.

Cómo recuperar varias páginas de resultados

Una API puede devolver diez, cincuenta o cien registros por respuesta, aunque existan miles. El cliente necesita descubrir si hay más información y realizar nuevas llamadas sin solicitar indefinidamente la misma página.

JSONPlaceholder admite parámetros de paginación de prueba. El siguiente patrón recupera páginas de diez elementos y limita deliberadamente el número de peticiones:

$todos = @()
$limite = 10
$maxPaginas = 5

for ($pagina = 1; $pagina -le $maxPaginas; $pagina++) {
    $uri = "https://jsonplaceholder.typicode.com/posts?_page=$pagina&_limit=$limite"

    $lote = Invoke-RestMethod `
        -Uri $uri `
        -Method Get `
        -TimeoutSec 20 `
        -ErrorAction Stop
    $lote = @($lote)

    if ($lote.Count -eq 0) {
        break
    }

    $todos += $lote

    if ($lote.Count -lt $limite) {
        break
    }
}

"Registros recuperados: $($todos.Count)"

El límite de cinco páginas es intencionado: evita que una prueba recorra sin control un servicio externo. Este ejemplo es adecuado para comprender una paginación basada en números de página; no todas las API utilizan ese sistema. Algunas devuelven un enlace a la página siguiente, un cursor, una marca temporal o un indicador específico. Copia el mecanismo que documente el servicio, no uno supuesto.

Si necesitas repetir consultas periódicas, pregunta además si existe un filtro de «modificados desde» para evitar descargar todos los datos en cada ejecución.

Ejemplo práctico: script de PowerShell para consultar y exportar datos

Una vez entendidos los elementos básicos, podemos convertir una consulta en una tarea reproducible. El siguiente script solicita las publicaciones de un usuario ficticio, comprueba que llegaron los campos esenciales y guarda un archivo CSV para examinarlo con Excel u otra herramienta.

Guárdalo como Exportar-PostsApi.ps1. El único destino local es un directorio salida situado junto al archivo del script; no escribe en servicios externos.

# Exportar-PostsApi.ps1
# Compatible con Windows PowerShell 5.1 y PowerShell 7.

$ErrorActionPreference = 'Stop'

$usuarioId = 1
$uri = "https://jsonplaceholder.typicode.com/posts?userId=$usuarioId"
$directorio = Join-Path -Path $PSScriptRoot -ChildPath 'salida'
$destino = Join-Path -Path $directorio -ChildPath 'posts-usuario-1.csv'

try {
    # 1. Consultar el servicio y tratar el resultado como colección.
    $posts = Invoke-RestMethod `
        -Uri $uri `
        -Method Get `
        -TimeoutSec 20 `
        -ErrorAction Stop
    $posts = @($posts)

    # 2. Comprobar la forma básica del resultado.
    if ($posts.Count -eq 0) {
        throw 'La API devolvió una colección vacía.'
    }

    foreach ($post in $posts) {
        if ($null -eq $post.id -or $null -eq $post.title) {
            throw 'La API devolvió un registro incompleto.'
        }
    }

    # 3. Preparar la carpeta de salida.
    if (-not (Test-Path -LiteralPath $directorio)) {
        New-Item -ItemType Directory -Path $directorio -Force | Out-Null
    }

    # 4. Seleccionar únicamente los campos necesarios.
    $posts |
        Select-Object id, userId, title |
        Export-Csv -LiteralPath $destino -NoTypeInformation -Encoding UTF8

    Write-Host "Exportados $($posts.Count) registros."
    Write-Host "Archivo: $destino"
}
catch {
    Write-Warning 'No se pudo completar la consulta o la exportación.'
    exit 1
}

Qué aporta respecto a un comando aislado

• Resultado verificable: no se genera un CSV silenciosamente a partir de una colección vacía o de registros sin campos esenciales.
• Tiempo de espera: una conexión que no responde no queda abandonada indefinidamente.
• Ruta controlada: la salida se construye a partir de la ubicación del script, con independencia de la carpeta de trabajo de la consola.
• Error identificable: devuelve un código de salida distinto de cero cuando no puede terminar.
• Datos mínimos: el archivo conserva únicamente las columnas necesarias para la demostración.

El ejemplo omite intencionadamente reintentos, escritura transaccional, registro estructurado e integración con credenciales: no son necesarios para enseñar la primera exportación y requieren políticas propias cuando existen datos reales. Tampoco garantiza que un consumidor nunca vea un CSV incompleto si se interrumpe la escritura; cuando ese requisito importe, utiliza un archivo temporal y una estrategia controlada de publicación del resultado.

Ejecutarlo manualmente antes de programar una tarea

Abre PowerShell, sitúate en la carpeta que contiene el archivo y ejecútalo de acuerdo con la política de ejecución de tu equipo:

# Situarse en la carpeta del script
Set-Location 'C:\MisScripts'

# Ejecutar el archivo
.\Exportar-PostsApi.ps1

# Comprobar el resultado
Import-Csv '.\salida\posts-usuario-1.csv' |
    Select-Object -First 3

C:\MisScripts es una ruta ilustrativa que debes adaptar. La política de ejecución no debe modificarse globalmente solo para hacer funcionar una prueba: utiliza los procedimientos aprobados en tu organización y comprueba el origen de los scripts antes de ejecutarlos.

Buenas prácticas antes de llevar el script a producción

Que una petición funcione una vez no significa que pueda ejecutarse de forma desatendida todos los días. En equipos técnicos pequeños, un script comprensible, documentado y fácilmente comprobable suele resultar más valioso que una solución cargada de dependencias innecesarias.

Comprobar qué se consulta y con qué identidad

Separa URL, configuración, permisos y secretos. Utiliza una credencial de alcance limitado y revisa qué información puede recuperar. Si el script se va a ejecutar desde otro equipo o una tarea programada, prueba esa misma identidad y ese mismo entorno antes de darlo por válido.

Guardar evidencias suficientes, pero no información sensible

Registrar fecha, operación, resultado y número de registros facilita distinguir una ejecución real de una que terminó sin hacer nada. Sin embargo, no conviene volcar respuestas completas, encabezados de autorización ni URLs que incluyan credenciales. Si el proceso crece, puedes ampliar la instrumentación siguiendo las pautas para registrar llamadas a una API.

Controlar llamadas repetidas y recuperación

La política de espera debe obedecer a la API. Diferencia fallos temporales de errores permanentes y no repitas escrituras cuya ejecución sea incierta. La lectura en lotes, los filtros por fecha y la paginación adecuada reducen trabajo, pero exigen conocer el contrato. Si aparecen varios servicios o ejecuciones, puede ser útil estudiar cómo diseñar scripts reutilizables para consumir distintas APIs.

Checklist de puesta en marcha

• ¿Están confirmadas la versión de PowerShell y las opciones disponibles?
• ¿La URL y los métodos corresponden al entorno correcto, especialmente si permite escrituras?
• ¿Se han probado respuestas correctas, vacías, incompletas y con error?
• ¿Se gestionan tiempo de espera, paginación y límites de consumo?
• ¿La autenticación utiliza HTTPS y evita secretos incrustados en el código?
• ¿La salida contiene únicamente los datos necesarios?
• ¿Hay una persona responsable de revisar los fallos y los cambios de contrato?

En procesos que deban funcionar durante años, añade controles de versiones, pruebas periódicas y una política de mantenimiento. Puedes ampliar esa perspectiva en las buenas prácticas para mantener integraciones mediante APIs a largo plazo.

Preguntas frecuentes sobre el consumo de APIs REST con PowerShell

Conclusión: de una consulta manual a una integración que puedes controlar

Consumir una API REST desde PowerShell empieza con una instrucción Invoke-RestMethod, pero el verdadero valor aparece cuando comprendes qué recurso estás consultando, qué significa su respuesta y cómo evitar que un fallo pase inadvertido. Saber trabajar con GET, JSON, encabezados y objetos abre la puerta a tareas de extracción, comprobación y tratamiento de información sin depender de operaciones manuales.

El camino recomendable es progresivo: primero una consulta de lectura, después la validación del resultado, a continuación una exportación local y solo cuando exista una necesidad justificada, autenticación, operaciones de escritura y ejecución programada. Esta secuencia ayuda a construir habilidades técnicas aplicables tanto a la administración de sistemas como a la integración de herramientas profesionales.