Cómo consumir una API REST desde MATLAB

Introducción

MATLAB no tiene por qué limitarse a archivos locales, matrices o modelos ya preparados. Mediante una API REST puede obtener información de otros sistemas, enviar resultados y conectar un análisis con datos que cambian. Para hacerlo intervienen las peticiones HTTP, los documentos JSON y una automatización que conviene diseñar con controles explícitos.

Imagina que necesitas recuperar mediciones de una aplicación de mantenimiento, analizarlas en MATLAB y generar una tabla para una revisión técnica. Copiar los valores a mano puede funcionar una vez; repetirlo cada día crea retrasos y errores. Una llamada a la API permite acceder a esos datos desde un script, siempre que tengas autorización y conozcas el contrato del servicio.

Esta guía se centra en cómo consumir una API REST desde MATLAB: realizar solicitudes GET y POST con webread y webwrite, incorporar parámetros y credenciales, interpretar respuestas, detectar problemas y preparar un script reutilizable. Los ejemplos de lectura usan un servicio público de pruebas; las direcciones genéricas se señalan expresamente para que no se confundan con servicios reales.

Índice

Qué necesitas antes de conectar MATLAB a una API

Una API REST expone recursos a través de direcciones URL y define cómo consultarlos o modificarlos mediante métodos HTTP. MATLAB actúa como cliente: construye una petición, la envía al servidor y recibe una respuesta. No es necesario programar el servidor ni instalar herramientas ajenas a MATLAB para comenzar con las funciones de acceso web incluidas en el producto.

Antes de escribir el script, reúne cuatro elementos: la URL base del servicio, la documentación de sus rutas, el método que acepta cada una y el formato de datos esperado. Cuando el servicio sea privado, añade el mecanismo de autenticación y los permisos de la cuenta técnica.

• Endpoint: una ruta específica, por ejemplo /v1/mediciones, añadida a la dirección del servidor.
• Método: GET para leer; POST para enviar o crear; PUT, PATCH y DELETE cuando el contrato permite otras operaciones.
• Cabeceras: información como Accept, Content-Type o Authorization.
• Contrato de respuesta: campos JSON, tipos de datos, paginación, códigos de error y restricciones de uso.

En los ejemplos ejecutables se emplea https://jsonplaceholder.typicode.com, una API de demostración con publicaciones y tareas ficticias. Las operaciones de escritura que acepta son simuladas: sirven para practicar la llamada, pero no guardan cambios permanentes. Para una API empresarial tendrás que sustituir las rutas y estructuras por las descritas por su proveedor.

Funciones de MATLAB para trabajar con REST

La vía más sencilla es la familia de funciones web. Cada una tiene una responsabilidad concreta y evita tener que ensamblar manualmente la mayoría de los mensajes HTTP.

No conviene confundir ContentType con MediaType. En weboptions, ContentType influye en cómo MATLAB interpreta la respuesta; MediaType especifica el tipo del contenido que se envía, por ejemplo JSON. Si el servidor devuelve correctamente application/json, MATLAB puede transformar la respuesta de forma automática.

La referencia técnica de MathWorks explica los argumentos admitidos por webread, webwrite y weboptions. Consultarla es especialmente útil si trabajas con distintas versiones de MATLAB o con servidores que utilizan convenciones particulares.

Primera petición GET con webread

La forma más directa de empezar consiste en consultar un recurso público. Abre MATLAB, crea un script .m y ejecuta estas instrucciones:

url = 'https://jsonplaceholder.typicode.com/posts/1';
opciones = weboptions('Timeout', 15, 'ContentType', 'json');

publicacion = webread(url, opciones);
disp(publicacion.title);
fprintf('Identificador: %d\n', publicacion.id);

La URL identifica la publicación número 1. weboptions fija una espera máxima de 15 segundos y solicita que la respuesta se interprete como JSON. webread realiza la petición GET y devuelve su contenido. En este ejemplo, el resultado es una estructura de MATLAB con campos como userId, id, title y body.

El campo title se puede consultar con la notación habitual publicacion.title. Que una API devuelva JSON no significa que recibas siempre una estructura: la conversión depende de si el JSON contiene un objeto, una lista, valores numéricos o tipos mezclados.

Qué ocurre si llamas a una URL distinta

Una dirección terminada en /posts devuelve una colección, mientras que /posts/1 devuelve un elemento concreto. La diferencia afecta a cómo se recorren los datos y a las comprobaciones que debe efectuar el script. Además, un servidor puede exigir cabeceras o permisos que el ejemplo público no necesita.

Parámetros de consulta y listas de resultados

Muchas APIs permiten filtrar los recursos con parámetros añadidos a la URL. En MATLAB es preferible pasar esos parámetros a webread en pares nombre-valor: así no tienes que concatenar manualmente ?, & y caracteres que podrían requerir codificación.

url = 'https://jsonplaceholder.typicode.com/posts';
opciones = weboptions('Timeout', 15, 'ContentType', 'json');

publicaciones = webread(url, 'userId', 1, opciones);
fprintf('Registros recibidos: %d\n', numel(publicaciones));

El servicio de demostración acepta userId=1 y devuelve las publicaciones asociadas a ese identificador. El resultado es una colección de objetos homogéneos, representable como un array de estructuras.

for k = 1:numel(publicaciones)
    fprintf('%d: %s\n', publicaciones(k).id, ...
        publicaciones(k).title);
end

El ejemplo recorre los elementos sin dar por supuesto cuántos hay. En una API profesional, un filtro puede tener otro nombre, utilizar fechas en formato ISO 8601 o emplear rutas y parámetros de paginación específicos. Los nombres de los parámetros no los decide MATLAB: los define el servidor.

Interpretar y validar datos JSON

Consumir la API es únicamente la primera mitad del trabajo. La segunda consiste en comprobar que los datos recibidos cumplen lo que necesita tu análisis. Un HTTP 200 no garantiza que aparezcan los campos esperados ni que estos tengan valores útiles.

Leer campos con comprobaciones

url = 'https://jsonplaceholder.typicode.com/posts/1';
dato = webread(url, weboptions('ContentType', 'json'));

if ~isstruct(dato) || ~isfield(dato, 'id') || ...
        ~isfield(dato, 'title')
    error('La respuesta no contiene los campos esperados.');
end

if ~isnumeric(dato.id) || ~isscalar(dato.id)
    error('El identificador tiene un formato inesperado.');
end

fprintf('Registro validado: %d\n', dato.id);

isstruct, isfield e isnumeric permiten detectar incompatibilidades antes de entrar en los cálculos. Cuando el servidor cambie el contrato, resulta preferible detener el procesamiento con una explicación clara a generar un informe aparentemente válido basado en campos ausentes.

Cuándo utilizar jsondecode y jsonencode

Si webread ya interpreta correctamente el JSON, no debes aplicar jsondecode por segunda vez. Estas funciones tienen sentido cuando trabajas con texto JSON sin transformar o necesitas construir una representación JSON explícita.

texto = '{"sensor":"S-01","valor":18.6}';
dato = jsondecode(texto);

fprintf('Valor recibido: %.1f\n', dato.valor);

nuevoTexto = jsonencode(dato);
disp(nuevoTexto);

Una lista JSON de objetos homogéneos suele convertirse en un array de estructuras; los objetos con distintas propiedades pueden dar lugar a celdas de estructuras. Los valores null, las fechas enviadas como texto y los nombres de campo que MATLAB necesita adaptar merecen una comprobación específica. Para profundizar en conversiones y estructuras, consulta cómo trabajar con respuestas JSON desde distintos lenguajes.

Enviar JSON con POST y webwrite

Algunas integraciones no se limitan a leer. También tienen que comunicar una medida procesada, registrar una incidencia o enviar el resultado de un cálculo. En ese escenario suele aparecer POST: el script prepara un cuerpo y el servidor decide si lo admite.

url = 'https://jsonplaceholder.typicode.com/posts';

nuevoRegistro = struct( ...
    'userId', 1, ...
    'title', 'Incidencia de prueba', ...
    'body', 'Ejemplo enviado desde MATLAB');

opciones = weboptions( ...
    'MediaType', 'application/json', ...
    'ContentType', 'json', ...
    'Timeout', 15);

respuesta = webwrite(url, nuevoRegistro, opciones);
disp(respuesta);

nuevoRegistro es una estructura de MATLAB. Al especificar MediaType como application/json, webwrite puede serializarla y enviarla como JSON. ContentType solicita que MATLAB interprete como JSON la respuesta de la API.

Esta operación es una simulación: JSONPlaceholder devuelve una respuesta ilustrativa, pero no conserva el registro como lo haría una base de datos real. En producción, no interpretes recibir una respuesta como garantía suficiente de que el proceso de negocio terminó: comprueba el estado, el identificador devuelto y las reglas del contrato.

Si el proveedor utiliza PUT, PATCH o DELETE, debes estudiar su documentación y establecer explícitamente el método admitido. No basta con cambiar el nombre de una función: hay que conocer la semántica de la operación, sus permisos y el riesgo de repetirla. El artículo cómo enviar datos JSON correctamente a una API desarrolla con más amplitud el diseño del cuerpo y su validación.

Autenticación con Bearer token y API Key

Una API privada suele exigir una credencial. Dos esquemas habituales son un token Bearer en la cabecera Authorization y una API Key en una cabecera definida por el proveedor. MATLAB puede enviar ambas utilizando HeaderFields de weboptions.

Ejemplo con token Bearer

token = getenv('API_TOKEN');
if isempty(token)
    error('No se ha configurado API_TOKEN.');
end

cabeceras = {'Authorization', ['Bearer ' token]};
opciones = weboptions( ...
    'HeaderFields', cabeceras, ...
    'ContentType', 'json', ...
    'Timeout', 20);

% Sustituir por una ruta real y autorizada.
datos = webread('https://api.ejemplo.com/v1/mediciones', opciones);

En este ejemplo API_TOKEN es el nombre de una variable de entorno, no el token. La dirección https://api.ejemplo.com/v1/mediciones es ilustrativa y debe sustituirse por un endpoint autorizado. El proveedor puede exigir otros permisos, rutas o cabeceras.

Ejemplo con API Key

clave = getenv('API_KEY');
if isempty(clave)
    error('No se ha configurado API_KEY.');
end

opciones = weboptions( ...
    'HeaderFields', {'X-API-Key', clave}, ...
    'ContentType', 'json', ...
    'Timeout', 20);

% Endpoint ilustrativo; adaptar al proveedor.
datos = webread('https://api.ejemplo.com/v1/mediciones', opciones);

El nombre X-API-Key es únicamente un ejemplo frecuente: cada servicio fija la ubicación y el nombre correctos. No copies una clave real en el artículo, el repositorio o una captura de pantalla. En un entorno con varios usuarios, protege además la configuración de ejecución y los registros del proceso.

Si necesitas decidir entre ambos esquemas o conocer sus límites, amplía la lectura con el uso de tokens Bearer y la autenticación mediante API Key. La elección corresponde al contrato y a la política de acceso de la API, no a una preferencia del script.

Comprobar códigos de respuesta HTTP

Las funciones webread y webwrite resultan cómodas, pero para inspeccionar directamente el código HTTP conviene utilizar la interfaz de clases matlab.net.http. Así puedes diferenciar con más precisión el transporte, el estado devuelto y el contenido de la respuesta.

import matlab.net.http.*

url = 'https://jsonplaceholder.typicode.com/posts/1';
solicitud = RequestMessage('GET', ...
    HeaderField('Accept', 'application/json'));
respuesta = solicitud.send(url);

if respuesta.StatusCode == StatusCode.OK
    dato = respuesta.Body.Data;
    disp(dato);
else
    fprintf('Código HTTP: %s\n', string(respuesta.StatusCode));
end

RequestMessage representa la petición, send la transmite y ResponseMessage permite revisar StatusCode, las cabeceras y Body.Data. En este caso se compara con la constante StatusCode.OK, correspondiente al código 200.

Para un script orientado únicamente a una lectura sencilla suele bastar webread con un bloque try/catch. Reserva el nivel HTTP más detallado para integraciones en las que sea necesario tomar decisiones distintas según el código o examinar cabeceras como las de paginación y limitación de tasa.

Los códigos orientan, pero el significado operativo depende también de la API. Un 403, por ejemplo, puede tener que ver con permisos sobre un recurso concreto y no con que el token haya caducado.

Errores, tiempos de espera y límites de uso

Las peticiones fallan por causas distintas: URL equivocada, caída de red, error de certificado, credenciales sin permisos, formato inesperado o demasiadas llamadas. El código debe distinguir esos escenarios antes de reintentar.

Controlar un fallo sin ocultarlo

url = 'https://jsonplaceholder.typicode.com/posts/1';
opciones = weboptions('Timeout', 15, 'ContentType', 'json');

try
    dato = webread(url, opciones);
    fprintf('Consulta terminada. ID: %d\n', dato.id);
catch ME
    % No imprimir credenciales ni cuerpos completos.
    fprintf(2, 'Fallo de consulta. Tipo: %s\n', ME.identifier);
    % Fallar de forma explícita para no procesar datos inexistentes.
    error('API:ConsultaFallida', 'La consulta no pudo completarse.');
end

El ejemplo comunica un identificador técnico y evita imprimir el contenido completo de la petición. En sistemas reales, prepara registros que incluyan fecha, operación e identificador de ejecución, sin tokens ni datos personales innecesarios. Tampoco conviene convertir cualquier excepción en una respuesta vacía: esa práctica puede introducir errores silenciosos en tus cálculos.

Configurar los tiempos de espera

Timeout impide que una espera se prolongue indefinidamente. El valor apropiado depende del volumen de respuesta, la conectividad y el trabajo esperado. Una descarga de archivo grande no requiere el mismo tratamiento que una consulta pequeña para actualizar un indicador.

Cuándo reintentar y cuándo no

• Lecturas GET: pueden admitir reintentos acotados ante fallos transitorios, con pausas crecientes y límite total de ejecución.
• HTTP 429: requiere respetar las cuotas y, cuando exista, la cabecera Retry-After; no implica reintentar inmediatamente.
• 401, 403 o 400: normalmente requieren corregir credenciales, permisos o petición, no repetirla muchas veces.
• POST de creación: no debe repetirse ciegamente después de un timeout, porque el servidor podría haber completado la operación. Utiliza claves de idempotencia solo si la API las admite.

Para un diagnóstico por capas, consulta cómo detectar errores habituales al consumir APIs; para planificar la frecuencia de consulta, cómo controlar límites de uso y cuotas de una API.

Recorrer resultados paginados

Una API suele limitar cuántos registros entrega en una sola respuesta. Pedir una lista no equivale a haberla recuperado por completo. El servidor puede utilizar números de página, desplazamientos (offset) o un cursor que señala la continuación.

El siguiente ejemplo utiliza los parámetros _page y _limit aceptados por el servicio de pruebas. Aplica un máximo de páginas y se detiene si deja de recibir elementos:

base = 'https://jsonplaceholder.typicode.com/posts';
opciones = weboptions('Timeout', 15, 'ContentType', 'json');
limite = 5;
maxPaginas = 4; % Límite deliberado de la demostración.
todos = [];

for pagina = 1:maxPaginas
    lote = webread(base, '_page', pagina, ...
        '_limit', limite, opciones);

    if isempty(lote)
        break;
    end

    if isempty(todos)
        todos = lote(:);
    else
        todos = [todos; lote(:)]; %#ok<AGROW>
    end

    if numel(lote) < limite
        break;
    end
end

fprintf('Recibidos hasta %d registros.\n', numel(todos));

En una API propia no copies esos nombres sin comprobarlos. Algunas respuestas incluyen una URL next; otras devuelven un cursor opaco. También es posible que el número de resultados cambie entre páginas cuando el origen se actualiza mientras consultas.

Para obtener lotes coherentes durante procesos de análisis, pregunta si la API soporta orden estable, marcas temporales, filtrado incremental o instantáneas. El límite máximo de páginas protege de bucles interminables, pero no garantiza por sí solo que se haya descargado todo; el script debe señalar cuando alcance el límite previsto.

Guardar y analizar la información obtenida

Una vez recibidos los datos, MATLAB resulta especialmente útil para convertirlos en tablas, revisar distribuciones, calcular indicadores y alimentar análisis técnicos. Conviene separar la extracción de la transformación: así podrás volver a procesar una descarga sin repetir innecesariamente las consultas.

Convertir estructuras en una tabla

url = 'https://jsonplaceholder.typicode.com/posts';
datos = webread(url, 'userId', 1, ...
    weboptions('ContentType', 'json'));

T = struct2table(datos);
T = T(:, {'id', 'userId', 'title'});

disp(T(1:min(5, height(T)), :));

struct2table permite trabajar con columnas cuando la respuesta es un array de estructuras homogéneo. La tabla es adecuada para filtrado, agregación y exportación. Antes de asumir que todos los registros comparten tipos, revisa los casos con propiedades opcionales y los valores vacíos.

Analizar una serie numérica procedente de JSON

Este segundo fragmento utiliza un JSON local inventado solo para ilustrar la transformación; no representa una medición real ni proviene del servicio de publicaciones:

texto = '{"sensor":"S-01","medidas":[12.4,13.1,12.8]}';
serie = jsondecode(texto);

media = mean(serie.medidas);
fprintf('Media de %s: %.2f\n', serie.sensor, media);

Al convertir los datos a un vector puedes utilizar las funciones habituales de MATLAB, como mean, max, min o procedimientos más específicos de análisis. La interpretación depende del origen: una media no es útil si mezclas unidades, periodos o sensores incompatibles.

Conservar una copia de la respuesta original

url = 'https://jsonplaceholder.typicode.com/posts/1';
archivo = websave('respuesta_original.json', url);

disp(archivo);
dato = jsondecode(fileread(archivo));

websave descarga el contenido a un archivo sin transformarlo previamente en una tabla. Esto facilita una revisión posterior y permite comparar el dato de origen con las operaciones realizadas. Si guardas datos confidenciales, aplica permisos, política de conservación y borrado acordes con su naturaleza. Para enfoques más amplios de destino y explotación de datos, consulta la integración de APIs con hojas de cálculo empresariales.

Ejemplo completo: de una API REST a un CSV con MATLAB

Esta secuencia reúne los pasos principales en un script sencillo. Consulta una API pública de pruebas, pide las publicaciones de un usuario, valida la estructura, transforma los resultados en una tabla y genera un archivo CSV.

% Ejemplo didáctico: leer publicaciones y exportarlas.
base = 'https://jsonplaceholder.typicode.com/posts';
opciones = weboptions('Timeout', 15, 'ContentType', 'json');

try
    datos = webread(base, 'userId', 1, opciones);

    if isempty(datos) || ~isstruct(datos)
        error('API:RespuestaVacia', ...
            'No se ha recibido una lista válida de publicaciones.');
    end

    campos = {'id', 'userId', 'title'};
    if ~all(isfield(datos, campos))
        error('API:ContratoInvalido', ...
            'Faltan campos necesarios en el JSON.');
    end

    ids = [datos.id]';
    usuarios = [datos.userId]';
    titulos = string({datos.title})';

    T = table(ids, usuarios, titulos, ...
        'VariableNames', {'Id', 'UsuarioId', 'Titulo'});

    archivo = fullfile(pwd, 'publicaciones_api.csv');
    writetable(T, archivo);

    fprintf('Exportados %d registros a %s\n', ...
        height(T), archivo);
catch ME
    fprintf(2, 'Proceso no completado (%s).\n', ME.identifier);
    % El archivo de una ejecución anterior no representa datos nuevos.
    error('API:ExportacionFallida', ...
        'La exportación no se ha completado.');
end

El archivo publicaciones_api.csv se crea en el directorio de trabajo actual de MATLAB. La primera columna conserva los identificadores de las publicaciones; la segunda, el usuario asociado; la tercera, el texto del título. Si la API devuelve una colección vacía o campos inesperados, el script informa del problema en vez de construir un archivo engañoso.

Para llevar este patrón a un sistema propio tendrás que sustituir el endpoint, añadir su autenticación si procede, adaptar las columnas al contrato real y decidir cómo actuar cuando cambien las respuestas. El ejemplo es ejecutable como demostración, pero no constituye un conector empresarial completo.

Seguridad y mantenimiento en un entorno profesional

Un script que funciona una tarde puede convertirse en una dependencia importante si alimenta informes periódicos, decisiones técnicas o procesos de una microempresa. Para que siga siendo útil, documenta el alcance y adopta controles sencillos desde el principio.

• Credenciales fuera del código: utiliza variables de entorno o un gestor de secretos. Limita permisos y prevé la rotación de claves.
• HTTPS con validación: no desactives la comprobación de certificados para ocultar errores de conectividad.
• Parámetros configurables: separa URL base, tiempos de espera, frecuencia y rutas de salida de las reglas de análisis.
• Validación explícita: comprueba campos obligatorios, tipos, unidades, intervalos y registros duplicados.
• Trazabilidad mínima: registra cuándo se ejecutó la consulta, qué recurso se utilizó y si el resultado fue completo, evitando secretos.
• Recuperación controlada: distingue entre no haber recibido respuesta y haber recibido una respuesta sin datos.
• Dependencia documentada: anota versión de MATLAB, contrato de la API y responsables de revisar cambios.

Si el objetivo es consultar varias APIs de forma consistente, resulta útil separar una función que realiza la petición de otra que interpreta los datos y otra que construye el informe. El criterio de diseño se amplía en cómo diseñar scripts reutilizables para consumir múltiples APIs. Si las consultas deben ejecutarse periódicamente, revisa también cómo descargar automáticamente datos de una API todos los días.

Antes de pasar a producción, verifica el contrato real: endpoint, credenciales, volumen, paginación, límite de llamadas, respuesta ante fallos y requisitos de protección de datos. MATLAB puede resolver el acceso y el análisis, pero la fiabilidad depende de cómo se integran esas piezas en el trabajo cotidiano.

Preguntas frecuentes sobre las API REST en MATLAB

Conclusión: convertir una consulta web en un flujo de análisis fiable

Consumir una API REST desde MATLAB comienza con una llamada pequeña, como un GET mediante webread, pero su verdadero valor aparece al incorporar validación, tratamiento de JSON, autenticación y una salida útil para el análisis. webwrite permite enviar información; weboptions controla aspectos esenciales de la comunicación; y matlab.net.http ofrece mayor detalle cuando los códigos y cabeceras importan.

El siguiente paso práctico es tomar un endpoint de lectura autorizado, documentar sus campos, ejecutar una consulta acotada y transformar la respuesta en una tabla verificable. Solo después conviene automatizarla y ampliar su alcance. De esa forma, una integración sencilla puede seguir siendo comprensible, segura y mantenible cuando deje de ser una prueba puntual.