API REST

Appeler des API REST avec une authentification basique, par jeton ou personnalisée

  1. API REST avec authentification basique
  2. API REST avec authentification par jeton
  3. API REST avec authentification par jeton sécurisé
  4. API REST avec en-têtes personnalisés
  5. Certificats et délais d’attente

API REST avec authentification basique

Appelez une API REST avec l’utilisateur et le mot de passe d’un identifiant enregistré :

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 avec authentification par jeton

Appelez une API REST avec un jeton bearer écrit dans l’expression :

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 avec authentification par jeton sécurisé

Appelez une API REST avec un jeton bearer tiré d’un identifiant enregistré, pour qu’il n’apparaisse jamais dans le formulaire :

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 avec en-têtes personnalisés

Appelez une API REST avec vos propres en-têtes, pour tout autre type d’authentification :

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

Certificats et délais d’attente

Depuis la 7.3.0, chaque fonction d’aide REST (fnRestBasic, fnRestAdvanced, fnRestJwt, fnRestJwtSecure) vérifie le certificat TLS du point de terminaison et cesse d’attendre après un délai fixé :

Paramètre Ce qu’il change
REST_IGNORE_CERTS 1 désactive la vérification du certificat. Jusqu’à la 7.2.0, il n’était jamais vérifié ; laissez-le à 0 et faites plutôt confiance à une CA privée avec NODE_EXTRA_CA_CERTS
REST_TIMEOUT_SECONDS Combien de temps un appel attend une réponse, 60 secondes par défaut ; un point de terminaison qui ne répond jamais fait alors échouer le champ au lieu de le bloquer

Depuis la 7.3.0, un champ dont le point de terminaison a un certificat auto-signé échoue avec une erreur de certificat tant que l’un des deux n’est pas défini. Appels REST et jq décrit les deux, et comment faire confiance à une CA privée pour tous les appels REST à la fois. fn.fnParseHtmlWithRegex n’est pas une fonction d’aide REST : elle ignore les deux paramètres, vérifie toujours le certificat et attend au maximum 30 secondes.