APIs REST

Llama a APIs REST con autenticación básica, por token o personalizada

  1. API REST con autenticación básica
  2. API REST con autenticación por token
  3. API REST con autenticación por token protegido
  4. API REST con cabeceras personalizadas
  5. Certificados y tiempos de espera

API REST con autenticación básica

Llama a una API REST con el usuario y la contraseña de una credencial almacenada:

fn.fnRestBasic(
  'get',
  'https://resturl/api/',
  '',
  'name_of_credential_in_database',
  '[.records[] | {name:.name, email:.email, spouse:.relations.spouse}]',
  'name',
  false
)

// output : a full json object coming from rest, json transformed with jq, result sorted and transformed by javascript.

// fn.fnRestBasic(method,url,body,credentialname,jq-expression,sort-object)
// - method : get,post,put,delete
// - url : url to restapi (can for example contain a placeholder like 'https://$(serverfield.fqdn)/api/'
// - body : in case of post and put
// - credential-name : it will lookup the credentials as you have saved in the gui
// - jq-expression : an optional jq-expression (https://jqplay.org)
// - sort object : a sort object to order the result
// - hasBigInt : a boolean indicating if it should convert Int64 to string

API REST con autenticación por token

Llama a una API REST con un bearer token escrito en la expresión:

fn.fnRestJwt(
  'get',
  'https://resturl/api/',
  '',
  'your_jwt_token_in_text',
  '[.records[] | {name:.name, age:.age}]',
  ['age','name'],
  false
)

// output : a full json object coming from rest, json transformed with jq, result sorted, first by age, then by name

// fn.fnRestJwt(method,url,body,token,jq-expression,sort-object)
// - method : get,post,put,delete
// - url : url to restapi (can for example contain a placeholder like 'https://$(serverfield.fqdn)/api/'
// - body : in case of post and put
// - token : it will be add as a Bearer Authorization header
// - jq-expression : an optional jq-expression (https://jqplay.org)
// - sort-object : a sort object to sort the result
// - hasBigInt : a boolean indicating if it should convert Int64 to string
// - tokenPrefix : a prefix, defaults to 'Bearer' (v5.0.0)

API REST con autenticación por token protegido

Llama a una API REST con un bearer token tomado de una credencial almacenada, de modo que nunca aparece en el formulario:

fn.fnRestJwtSecure(
  'get',
  'https://resturl/api/',
  '',
  'name_of_credential_in_database',
  '[.records[] | {name:.name, age:.age}]',
  ['age','name'],
  false
)

// output : a full json object coming from rest, json transformed with jq, result sorted, first by age, then by name

// fn.fnRestJwtSecure(method,url,body,token,jq-expression,sort-object)
// - method : get,post,put,delete
// - url : url to restapi (can for example contain a placeholder like 'https://$(serverfield.fqdn)/api/'
// - body : in case of post and put
// - credential_name : Encrypted credential will be looked up.  The password will be the token.
// - jq-expression : an optional jq-expression (https://jqplay.org)
// - sort-object : a sort object to sort the result   
// - hasBigInt : a boolean indicating if it should convert Int64 to string 
// - tokenPrefix : a prefix, defaults to 'Bearer' (v5.0.0)

API REST con cabeceras personalizadas

Llama a una API REST con cabeceras propias, para cualquier otro tipo de autenticación:

fn.fnRestAdvanced(
  'get',
  'https://resturl/api/',
  '',
  {'a_custom_http_header':'your_value','Authorization':'basic base64(my_rest_credential)'},
  '.records[].name',
  {name:{ignoreCase:true,direction:'desc'}},
  false,
  false
)

// output : a full json object coming from rest, json transformed with jq, result sorted descending by name

// fn.fnRestAdvanced(method,url,body,{myheader:'value'},jq-expression,sort-object)
// - method : get,post,put,delete
// - url : url to restapi (can for example contain a placeholder like 'https://$(serverfield.fqdn)/api/'
// - body : in case of post and put
// - headers: an object of headers
// - jq-expression : an optional jq-expression (https://jqplay.org)
// - sort-object : a sorting object to order the results
// - hasBigInt : a boolean indicating if it should convert Int64 to string
// - raw : return data and response_headers  
  
// 3 function-placeholders are allowed in the headers:
// - base64(credential_name) : will create a base64 encoded "username:password".  prefix with "basic" if required
// - username(credential_name) : will add the username of the credential
// - password(credential_name) : will add the password of the credential

Certificados y tiempos de espera

Desde 7.3.0, cada función auxiliar REST (fnRestBasic, fnRestAdvanced, fnRestJwt, fnRestJwtSecure) comprueba el certificado TLS del endpoint y deja de esperar tras un tiempo fijado:

Ajuste Qué cambia
REST_IGNORE_CERTS 1 omite la comprobación del certificado. Hasta 7.2.0 nunca se comprobaba; mantenlo en 0 y confía en una CA privada con NODE_EXTRA_CA_CERTS en su lugar
REST_TIMEOUT_SECONDS Cuánto espera una llamada una respuesta, 60 segundos por defecto; un endpoint que nunca responde hace fallar el campo en lugar de bloquearlo

Desde 7.3.0, un campo cuyo endpoint tiene un certificado autofirmado falla con un error de certificado hasta que se configura uno de los dos. Llamadas REST y jq describe ambos, y cómo confiar en una CA privada para todas las llamadas REST a la vez. fn.fnParseHtmlWithRegex no es una función auxiliar REST: ignora ambos ajustes, siempre comprueba el certificado y espera como máximo 30 segundos.