Adaptador API/Servicios Web

English

Introducción

A través del Adaptador API/Servicios Web, TAST se conecta con los servicios API REST que están disponibles en un punto final y los utiliza para realizar pruebas. Este Adaptador tiene un importante compañero llamado Web Services Mapping Assistant con una interfaz de usuario más detallada y compleja para ayudar a la creación de mensajes  y mapeos. 

Este Adaptador es utilizado para ejecutar pruebas de Servicios Web: REST, SOAP y otros. El Adaptador API/Servicios Web puede realizar todo tipo de llamadas y realizar comprobaciones sobre estas. Es posible realizar pruebas individuales con este adaptador o pruebas de extremo a extremo conectando con otros adaptadores.

Parámetros de Inicialización

En la configuración del Adaptador API/Webservice debemos incluir todos los datos que consideremos descriptivos del servicio en general y que se aplican a todas sus peticiones. Así el usuario no tendrá que indicarlo en cada mensaje del diagrama. Son los siguientes: 

• EndPoint: especifica la URL que es común a todas las peticiones sobre ese servicio web.
• Keep/Session: si marcamos esta casilla de verificación la sesión seguirá activa durante las diferentes llamadas o peticiones, y añadirá las cookies que reciba en las respuestas a las peticiones que realice.
• IsSecure: indica si las peticiones al servicio se enviaron a través del protocolo http o https..
• Headers(Opt.): permite agregar encabezados a todas las solicitudes que se envían al servicio.
• Service-Charset: es el conjunto de caracteres que se utilizaran en el servicio HTTP. El Service Charset el más común es UTF-8. 

Las palabras y oraciones en el texto se crean a partir de caracteres. Una codificación de caracteres proporciona una clave para desbloquear (es decir, descifrar) el código. Así, el conjunto de caracteres es la información de codificación, es decir, el conjunto de asignaciones entre los bytes del ordenador y los caracteres del conjunto de caracteres. Sin la clave, los datos parecen basura.  El Service Charset Cp1047 es usado por defecto.

• Authentication Type: permite seleccionar el tipo de autenticación que requiere el servicio. Una vez seleccionado nos permite introducir los datos necesarios para el tipo de autenticación seleccionado. Por defecto, no se usa autenticación.

Funciones Predefinidas (PF's)

• deleteRest(Resource, Headers, Charset, Body): permite configurar una petición HTTP de tipo Delete. Como parámetros de entrada tenemos:

  • • Resource: indica el recurso dentro del EndPoint en el que se realizará la solicitud.

    • Headers(Opt.): indica las cabeceras que deben añadirse a la solicitud.

    • Charset(Opt.):  para elegir el charset que queremos utilizar.

• •  

    • Body(Opt.): indica el contenido del parámetro.

• getALLJSONElementInfoByTagname: si el contenido de la respuesta a una petición es JSON o JsonArray, esta función permite recuperar todos los valores del atributo o elemento, con su nivel de profundidad en el JSON, y devolverlos bajo un TastTableData de tres columnas (TagName, Valor, Nivel). También se puede filtrar el resultado especificando el nivel bajo el que se debe encontrar el TagName. Como parámetros de entrada tenemos:

  • ResponseName: indica el nombre con el que se generó la respuesta Http.

  • JSonTagName: expresión de nombre de etiqueta utilizada para identificar el elemento.

  • LevelSelection:

• getALLJSONElementValueByTagname: si el contenido de la respuesta a una petición es JSON, esta función permite recuperar el valor de algún elemento, utilizando el TagName para identificarlo. Devuelve todos los elementos. El resultado se presenta con los valores separados por el carácter |, en el campo Mensaje / Resultado / Valor. Como parámetros de entrada tenemos:

  • • ResponseName: indica el nombre con el que se generó la respuesta Http.

    • JSonTagName: expresión de nombre de etiqueta utilizada para identificar el elemento.

• getALLXMLElementValueByTagName(ResponseName, ElementTag): si el contenido de la respuesta a una petición es XML, esta función permite recuperar los valores de todos los elementos, utilizando el TagName para identificarlo. En lugar de devolver sólo un elemento (el primero), este PF devuelve una lista de todos los elementos. Como parámetros de entrada tenemos:
  • • ResponseName: indica el nombre con el que se generó la respuesta Http.

  • • ElementTag: etiqueta XML´s utilizada para identificar el elemento.

• getCookieValue(ResponseName, Cookie): recuperar el valor de la cookie indicada.
  • • ResponseName: indica el nombre con el que se generó la respuesta Http.
    • Cookie: indica el nombre de Cookie´s a recuperar.

• getElementsCountByJsonPath(JsonPath, ResponseName): devuelve el número de elementos que tienen el mismo JsonPath.

  • • JsonPath: el JsonPath a buscar.

    • ResponseName: el nombre con el que se generó la respuesta HTTP.

• getElementsCountByTagName(tagName, ResponseName): devuelve el número de elementos que tienen el mismo tagName.

  • • tagName: el nombre de tag a buscar.

    • ResponseName: el nombre con el que se generó la respuesta HTTP.

• getElementsValueByJsonPath(JsonPath, ResponseName): devuelve todos los elementos que tienen el mismo JsonPath. 

  • • JsonPath: el JsonPath a buscar.

    • ResponseName: el nombre con el que se generó la respuesta HTTP.

• getHeaderValue(ResponseName, Header): permite obtener el valor de una cabecera recibida en una respuesta HTTP.

  • • ResponseName: indica el nombre con el que se generó la respuesta Http.

    • Headers: el nombre de la cabecera de la que desea extraer el valor.

• getHTMLElementValueByXpath(): si el contenido de la respuesta a una petición es HTML esta función permite recuperar el valor de un elemento empleando para identificar este, una expresión Xpath

  • • ResponseName: indica el nombre con el que se generó la respuesta Http.

    • XPathExp: expresión XPath utilizada para identificar el elemento.

• getJSONElementValueByJsonPath(ResponseName, JSonPathExp): si el contenido de la respuesta a una petición es JSON, esta función permite recuperar el valor de un elemento, utilizando el nombre de JsonPath para identificarlo. Si hay más de un elemento, devuelve el primero.
  • • ResponseName: indica el nombre con el que se generó la respuesta Http.
    • JSonPathExp: expresión de JSonPath utilizada para identificar el elemento.

• getJSONElementValueByTagName(ResponseName, TagnameExp): si el contenido de la respuesta a una petición es JSON, esta función permite recuperar el valor de un elemento, utilizando el TagName para identificarlo. Si hay más de un elemento, devuelve el primero. El resultado se presenta con los valores separados por el carácter |, en el campo Mensaje / Resultado / Valor.

  • • ResponseName: indica el nombre con el que se generó la respuesta Http.

    • JSonTagName: expresión Tagname utilizada para identificar el elemento.

• getResponseBody: obtener el cuerpo de la respuesta http, sin el código de respuesta ni otras cabeceras, sólo el cuerpo, es decir, el JSON o el XML.
  • • ResponseName:ResponseName

• getResponseStatus(ResponseName): permite recuperar el código de estado Http de la respuesta.

  • • ResponseName: indica el nombre con el que se generó la respuesta Http.

• getResponseTime: retorna el tiempo empleado en milisegundos en recibir la respuesta a una solicitud. Para identificar la respuesta recibe un parámetro con el nombre de la variable HttpResponse de la que queremos obtener la información.
  • • ResponseName:ResponseName

• getRest(Resource, Headers, Parameters): permite configurar una petición HTTP del tipo Get.

  • • Resource: indica el recurso dentro del EndPoint en el que se realizará la solicitud.

    • Headers: indica las cabeceras que deben añadirse a la solicitud.

    • Parameters: indica los parámetros que deben añadirse a la URL de la incidencia.

    • Charset: para elegir el charset que queremos utilizar.

• getXMLElementValueByTagName(ResponseName,  ElementTag): si el contenido de la respuesta a una petición es XML, esta función permite recuperar el valor de un elemento, empleando para identificar este elemento, su TagName. Si hay más de un elemento,  con este TagName se devolverá el valor del primer elemento.

  • • ResponseName: indica el nombre con el que se generó la respuesta Http.

    • ElementTag: XML´s etiqueta utilizada para identificar el elemento.

• getXMLElementValueByXPath(ResponseName, XPathExp): si el contenido de la respuesta a una petición es XML, esta función permite recuperar el valor de un elemento, utilizando para identificar este, una expresión XPath. Además permite buscar valores en respuestas con un tipo de contenido XHTML.

  • • ResponseName: indica el nombre con el que se generó la respuesta Http.

    • XPathExp: expresión XPath utilizada para identificar el elemento.

• patchRest(Resource, Headers, Content-type, Body):  permite configurar una petición HTTP de tipo Patch.

  • • Resource: indica el recurso dentro del EndPoint en el que se realizará la solicitud.

    • Headers: indica las cabeceras que deben añadirse a la solicitud.

    • Content-type: cabecera estándar HTTP que indica el tipo de contenido que se agrega al cuerpo de la solicitud.

    • Body: contenido de la solicitud Http.

    • Charset:

• postRest(Resource, Headers, Content-type, Body):  permite configurar una petición HTTP de tipo Post.

  • • Resource: indica el recurso dentro del EndPoint en el que se realizará la solicitud.

    • Headers: indica las cabeceras que deben añadirse a la solicitud.

    • Content-type: cabecera estándar HTTP que indica el tipo de contenido que se agrega al cuerpo de la solicitud.

    • Body: contenido de la solicitud Http.

    • Charset:
    • Parameters:

• putRest(Resource, Headers, Content-type, Body): permite configurar una petición HTTP de tipo Put.

  • • Resource: indica el recurso dentro del EndPoint en el que se realizará la solicitud.

    • Headers: indica las cabeceras que deben añadirse a la solicitud.

    • Content-type: cabecera estándar HTTP que indica el tipo de contenido que se agrega al cuerpo de la solicitud. 

• •  
  •  

    • Body: contenido de la solicitud Http.

    • Charset: para elegir el charset que queremos utilizar.

• responseBodyContainsText(ResponseName, SearchValue): busca una cadena de texto pasada como parámetro en el  cuerpo de la respuesta indicada como primer parámetro. 

  • • ResponseName: indica el nombre con el que se generó la respuesta Http.

    • SearchValue: texto a buscar dentro del cuerpo de la respuesta.

• setBasicAuthentication(User, Password): permite configurar el esquema de autenticación de las peticiones que se envían al endpoint como BasicAuthentication. Sobrescribe la configuración de seguridad realizada en la configuración del adaptador.

  • • User: código de usuario utilizado como credencial.

    • Password: contraseña para presentar como credencial.

• setBearerTokenAuthentication(Token): permite configurar el esquema de autenticación de las peticiones que se envían al endpoint como BearerTokenAuthentication. Sobrescribe la configuración de seguridad realizada en la configuración del adaptador. Como parámetro de entrada tenemos:

  • • Token: valor de Token que se presentará como credencial.

• setDigestAuthentication(User, Password, Realm, Nonce, Algorithm, Qoq, NonceCount, ClientNonce, Opaque): permite configurar el esquema de autenticación de las peticiones que se envían al endpoint como Digest Authentication Schema. Sobrescribe la configuración de seguridad realizada en la configuración del adaptador.

  • • Usuario: nombre de usuario utilizado como credencial.

    • Password: contraseña para presentar como credencial.

    • Realm: dominio de seguridad en el que debe realizarse la validación de seguridad. Es opcional, si no se conoce, el adaptador intentará realizar la validación con los datos obtenidos de la respuesta al desafío.

    • Nonce: nonce devuelto por el servidor. Es opcional, si no se conoce, el adaptador intentará realizar la validación con los datos obtenidos de la respuesta al desafío.

    • Algoritm: algoritmo utilizado para el cifrado. Es opcional, si no se conoce, el adaptador intentará realizar la validación con los datos obtenidos de la respuesta al desafío.

    • Qoq: calidad del código de protección. Es opcional, si no se conoce, el adaptador intentará realizar la validación con los datos obtenidos de la respuesta al desafío.

    • NonceCount: nonceCount asociado a la solicitud. Es opcional, si no se conoce, el adaptador intentará realizar la validación con los datos obtenidos de la respuesta al desafío.

    • ClienteNonce: nonce generado por el cliente. Es opcional, si no se conoce, el adaptador intentará realizar la validación con los datos obtenidos de la respuesta al desafío.

    • Opaque: opaque devuelto por el servidor. Es opcional, si no se conoce, el adaptador intentará realizar la validación con los datos obtenidos.

• setNoneAuthentication(): permite configurar el método de autenticación de las peticiones que se envían al EndPoint como peticiones sin esquema de autenticación. Sobrescribe la configuración de seguridad realizada en la configuración del adaptador.

Conceptos teóricos importantes relacionados con los Servicios Web

Base URL

Sería la parte de la URL que es común a todas las peticiones o peticiones sobre ese servicio web, de forma que el usuario no tenga que introducirla en cada mensaje que configure como servicio de petición.

Datos de autenticación y autorización

Se entiende que la primera interacción que el adaptador deberá realizar con el servicio web será la de autenticación y autorización. Actualmente existen varios métodos estándar diferentes para realizar este paso y otros propietarios que dejaría para desarrollar bajo demanda, es decir, si encontramos la necesidad.

Resaltar que no son métodos de autenticación-autorización propios de los servicios Web Rest, más bien están asociados al protocolo Http, por lo que el desarrollo debe estar orientado a ser reutilizado por el Adaptador GUI Html y el Adaptador Webservices SOAP, si en el futuro se pretende acceder a alguna aplicación Web que utilice alguno de estos métodos para autenticarse-autorizarse.

Tipos de autenticación

En la imagen siguiente vemos un desplegable con los distintos tipos de autenticación que TAST nos ofrece. El usuario debe seleccionar que tipo de autenticación necesita.

Vamos a enumerarlos y haremos una  breve descripción de los mismos y de los parámetros que podríamos necesitar según el tipo de autenticación que elijamos:

• No Authorization (NoAuth): si el usuario selecciona este método no es necesario autenticarse para utilizar el servicio.

• Digest Authorization (DigestAuth): este método es un poco más complicado porque la clave está encriptada y el usuario, en la herramienta postman cuando selecciona este tipo de autenticación, solicita los siguientes parámetros:
  
  

  • • User

    • Password
      
      Y como opcional (se utilizan valores por defecto si el usuario no los proporciona) lo siguiente:
      
      

    • Realm: dominio de seguridad contra el que autenticarse.

    • Nonce: código que el servidor emite en la respuesta cuando una petición no está autorizada. Es único por sesión y debe ser incluido en las siguientes solicitudes.

    • Algorithm: Algoritmo de encriptación. MD5 o MD5-sess.

    • Qop: calidad de protección, los valores posibles son auth (más común) o auth-int (autorización con integridad) creo que menos soportados y utilizados.

    • Nonce Count: número de peticiones realizadas al servidor con la misma unidad, su obligación depende del valor asignado a Qop.

    • Client Nonce:

    • Opaque: es un valor devuelto por el servidor en la primera respuesta no autorizada, y debe ser añadido sin modificar todas las peticiones posteriores al servidor. https://en.wikipedia.org/wiki/Digest_access_authentication  

• Basic Authorization (BasicAuth): el método más simple solo requiere de los parámetros usuario y password. https://en.wikipedia.org/wiki/Basic_access_authentication

• BearenToken

  • • Token

• CertificateAuth
  • • CertificatePath
    • PrivateKeyPath
    • Password

• OAuth 1.0: este método, Autorización abierta, es más moderno para crear un primer estándar relacionado con la autenticación. OAuth 2.0 se utiliza más pero podríamos encontrar un servicio que lo utilice. En Postman se solicitan los siguientes parámetros:

  • • ConsumerKey: un valor utilizado por el consumidor del servicio para identificarse con él.

    • ConsumerSecret: token utilizado por el consumidor para validar su propiedad de la ConsumerKey.

    • Access Token: ficha de acceso.

    • Token Secret: otra clave para asegurar la propiedad del token de acceso.
      
      Y como parámetros opcionales (valores por defecto si el usuario no entra):
      
      

    • Signature Method: el método de firma utilizado por el consumidor para firmar las solicitudes.

    • Timestamp: se añade una marca de tiempo a la solicitud.

    • Nonce: la cadena aleatoria generada por el cliente, se añadirá a todas las peticiones.

    • Realm: indica el dominio de seguridad que realiza la autenticación. https://es.wikipedia.org/wiki/OAuth

• OAuth 2.0: la evolución de OAuth 1.0, es el estándar más soportado por las grandes empresas de Internet, Google, Facebook, Twitter, etc., no siendo un experto, creo que es una autenticación de dos pasos. Postman sólo pide el parámetro:
  

  • • Ficha de acceso. código de acceso al servicio.
      Pero en la opción de solicitar una petición de token de acceso los datos se autentican contra el servicio que le va a dar el código de acceso para esa operación. Además de estos métodos, en Postman aparecen otros métodos de autenticación como por ejemplo:

    • Ficha al portador. https://swagger.io/docs/specification/authentication/bearer-authentication/
      

    • Firma de AWS. Método propietario para autenticar en servicios web en la plataforma de nube de Amazon. http://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html
      

    • Autenticación de Halcón. Nuevo. https://www.drupal.org/project/hawk_auth Implementar los diferentes métodos de autenticación en el Frontal.

Funciones

A continuación se muestra la lista de Funciones Predefinidas para el envío de peticiones al servidor proporcionadas por el adaptador, así como los parámetros necesarios para su ejecución. En reposo los tipos de peticiones se corresponden con los diferentes métodos/verbos contemplados en el protocolo HTTP. En principio habrá una función para formar una petición para cada método HTTP. Otro requisito es que se permita que las variables del diagrama compongan los diferentes campos de la solicitud.

Los métodos existentes son: