Entrades classificades amb: Web Services

Introducció als Serveis Web RESTful

Leer en castellano

Els serveis web REST (Transferència d’estat representacional) defineixen un conjunt de principis arquitectònics pels quals es dissenyen serveis web fent focus en els recursos del sistema, incloent com s’accedeix a l’estat d’aquests recursos i com es transfereixen per protocol HTTP cap a clients escrits en diversos llenguatges. REST ha emergit en els últims anys com el model predominant per al disseny de serveis. De fet, REST va aconseguir un impacte tan gran a la web que pràcticament va aconseguir desplaçar a SOAP i les interfícies basades en WSDL per tenir un estil bastant més simple d’utilitzar.

Es basa en 4 principis que descriuen la seva manera en que està implementat:

– Utilitza els mètodes HTTP de manera explícita.
– No manté l’estat.
– Exposa URIs amb forma de directoris.
– Transfereix XML, JavaScript Object Notation (JSON), o tots dos.

Utilitza els mètodes HTTP de manera explícita:
Una de les característiques claus dels serveis web REST és l’ús explícit dels mètodes HTTP, seguint el protocol definit per RFC 2616. Per exemple, HTTP GET es defineix com un mètode productor de dades, l’ús està pensat perquè les aplicacions client obtinguin recursos, busquin dades d’un servidor web, o executin una consulta esperant que la web la realitzi i retorni un conjunt de recursos .

REST fa que els desenvolupadors usin els mètodes HTTP explícitament de manera que resulti consistent amb la definició del protocol. Aquest principi de disseny bàsic estableix una associació un-a-un entre les operacions de crear, llegir, actualitzar i esborrar i els mètodes HTTP.

D’acord a aquesta associació:

–    S’usa POST per crear un recurs al servidor.
–    S’usa GET per obtenir un recurs.
–    S’usa PUT per canviar l’estat d’un recurs o actualitzar.
–    S’usa DELETE per eliminar un recurs.

Una falla de disseny poc afortunada que tenen moltes APIs web és l’ús de mètodes HTTP per a altres propòsits. Per exemple, la petició de la URI en una comanda HTTP GET, en general identifica un recurs específic. O el string de consulta al URI inclou un conjunt de paràmetres que defineixen el criteri de recerca que farà servir el servidor per trobar un conjunt de recursos. Almenys, així com el RFC HTTP/1.1 descriu l’GET.

No manté l’estat:
Els serveis web REST necessiten escalar per poder satisfer una demanda en constant creixement. S’usen clústers de servidors amb balanceig de càrrega i alta disponibilitat, proxies, i gateways de manera de conformar una topologia servicial, que permeti transferir peticions d’un equip a un altre per disminuir el temps total de resposta d’una invocació al servei web.
L’ús de servidors intermedis per millorar l’escalabilitat fa necessari que els clients de serveis web REST enviïn peticions completes i independents, és a dir, s’han d’enviar peticions que inclouen totes les dades necessàries per complir la comanda, de manera que els components en els servidors intermedis puguin redireccionar i gestionar la càrrega sense mantenir l’estat localment entre les peticions.

Una petició completa i independent fa que el servidor no hagi de recuperar cap informació de context o estat en processar la petició. Una aplicació o client de servei web REST  ha d’incloure dins de la capçalera i del cos HTTP de la petició tots els paràmetres, context i dades que necessita el servidor per generar la resposta. D’aquesta manera, el no mantenir estat millora el rendiment dels serveis web i simplifica el disseny i implementació dels components del servidor, ja que l’absència d’estat al servidor elimina la necessitat de sincronitzar les dades de la sessió amb una aplicació externa.

Exposa URIs amb forma de directoris:
Des del punt de vista del client de l’aplicació que accedeix a un recurs, la URI determina què tan intuïtiu serà el web service REST, i si el servei va a ser utilitzat tal com va ser pensat al moment de dissenyar-lo. La tercera característica dels serveis web REST és justament sobre les URIs.

Les URI dels serveis web REST han de ser intuïtives, fins al punt que sigui fàcil endevinar. Pensem en les URI com una interfície auto-documentada que necessita de molt poca o cap explicació o referència perquè un desenvolupador pugui comprendre al que apunta, i als recursos derivats relacionats.

Una forma d’aconseguir aquest nivell d’usabilitat és definir URIs amb una estructura a l’estil dels directoris. Aquest tipus d’URIs és jeràrquica, amb una única ruta arrel, i va obrint branques a través de les subrutes per exposar les àrees principals del servei. D’acord a aquesta definició, una URI no és només una cadena de caràcters delimitada per barres, sinó més aviat un arbre amb subordinats i pares organitzats com a nodes. Per exemple, en un servei de fils de discussions que té temes diversos, es podria definir una estructura d’URI com aquesta:

http://www.elmeuservei.org/discusio/temes/ {tema}

L’arrel, /discusio, té un node /temes com fill. Sota aquest node hi ha un conjunt de noms de temes (com ser tecnologia, actualitat, i més), cadascun dels quals apunta un fil de discussió. Dins d’aquesta estructura, resulta fàcil recuperar fils de discussió al tipejar alguna cosa després d’/ temes /.

En alguns casos, la ruta a un recurs encaixa molt bé dins la idea de “estructura de directoris”. Per exemple, prenguem alguns recursos organitzats per data, que són molt pràctics d’organitzar usant una sintaxi jeràrquica.

Transfereix XML, JavaScript Object Notation (JSON), o tots dos:
La representació d’un recurs en general reflecteix l’estat actual del mateix i els seus atributs al moment en què el client de l’aplicació realitza la petició. La representació del recurs són simples “fotos” en el temps. Això podria ser una representació d’un registre de la base de dades que consisteix en l’associació entre columnes i tags XML, on els valors dels elements en l’XML contenen els valors de les files. O, si el sistema té un model de dades, la representació d’un recurs és una fotografia dels atributs d’una de les coses en el model de dades del sistema.

L’última restricció al moment de dissenyar un servei web REST té a veure amb el format de les dades que l’aplicació i el servei s’intercanvien en les peticions/respostes. Aquí és on realment val la pena mantenir les coses simples, llegibles per persones, i connectades.

Els objectes del model de dades generalment es relacionen d’alguna manera, i les relacions entre els objectes del model de dades (els recursos) s’han de reflectir en la forma en què es representen al moment de transferir les dades al client. En el servei de fils de discussió anterior, un exemple d’una representació d’un recurs connectat podria ser un tema de discussió arrel amb tots els seus atributs, i links embeguts a les respostes al tema.

<discusio data=”{data}” tema=”{tema}”>
<comentari> {comentari} </comentari>
<respostes>
<resposta de = “gaz@mail.com “href =” /discussió/temes/{tema}/gaz “/>
<resposta de = “gir@mail.com “href =” /discussió/temes/{tema}/gir “/>
</respostes>
</discusio>

Conclusió: No sempre REST és la millor opció. Està sorgint com una alternativa per dissenyar serveis web amb menys dependència en middleware propietari (per exemple, un servidor d’aplicacions), que el seu contrapart SOAP i els serveis basats en WSDL. D’alguna manera, REST és la volta a la Web abans de l’aparició dels grans servidors d’aplicacions, ja que fa èmfasi en els primers estàndards d’Internet, URI i HTTP. XML sobre HTTP és una interfície molt poderosa que permet que aplicacions internes, com interfícies basades en JavaScript asíncron + XML (AJAX) puguin connectar-se, situar i consumir recursos. De fet, és justament aquesta gran combinació amb AJAX la que va generar aquesta gran atenció que ha tingut REST avui en dia.
Resulta molt flexible el poder exposar els recursos del sistema amb un API REST, de manera de brindar dades a diferents aplicacions, formats en diferents maneres. REST ajuda a complir amb els requeriments d’integració que són crítics per construir sistemes on les dades s’han de poder combinar fàcilment i estendre. Des d’aquest punt de vista, els serveis REST es converteixen en alguna cosa molt més gran.

Llegir en català

Los servicios web REST (Transferencia de estado representacional) definen un conjunto de principios arquitectónicos por los que se diseñan servicios web haciendo foco en los recursos del sistema, incluyendo cómo se accede al estado de estos recursos y cómo se transfieren por protocolo HTTP a clientes escritos en varios lenguajes. REST ha emergido en los últimos años como el modelo predominante para el diseño de servicios. De hecho, REST logró un impacto tan grande en la web que prácticamente logró desplazar a SOAP y las interfaces basadas en WSDL por tener un estilo bastante más simple de utilizar.

Se basa en 4 principios que describen su forma en que está implementado:

– Utiliza los métodos HTTP de manera explícita.
– No mantiene el estado.
– Expone URIs con forma de directorios.
– Transfiere XML, JavaScript Object Notation (JSON), o ambos.

Utiliza los métodos HTTP de manera explícita:
Una de las características claves de los servicios web REST es el uso explícito de los métodos HTTP, siguiendo el protocolo definido por RFC 2.616. Por ejemplo, HTTP GET se define como un método productor de datos, el uso está pensado para que las aplicaciones cliente obtengan recursos, busquen datos de un servidor web, o ejecuten una consulta esperando que la web la realice y devuelva un conjunto de recursos.

REST hace que los desarrolladores usen los métodos HTTP explícitamente de manera que resulte consistente con la definición del protocolo. Este principio de diseño básico establece una asociación uno-a-uno entre las operaciones de crear, leer, actualizar y borrar y los métodos HTTP.

De acuerdo a esta asociación:

– Se usa POST para crear un recurso en el servidor.
– Se usa GET para obtener un recurso.
– Se usa PUT para cambiar el estado de un recurso o actualizar.
– Se usa DELETE para eliminar un recurso.

Una falla de diseño poco afortunada que tienen muchas APIs web es el uso de métodos HTTP para otros propósitos. Por ejemplo, la petición de la URI en un pedido HTTP GET, en general identifica un recurso específico. O el string de consulta al URI incluye un conjunto de parámetros que definen el criterio de búsqueda que utilizará el servidor para encontrar un conjunto de recursos. Al menos, así como el RFC HTTP/1.1 describe el GET.

No mantiene el estado:
Los servicios web REST necesitan escalar para poder satisfacer una demanda en constante crecimiento. Se usan clústeres de servidores con balanceo de carga y alta disponibilidad, proxies, y gateways de manera de conformar una topología servicial, que permita transferir peticiones de un equipo a otro para disminuir el tiempo total de respuesta de una invocación al servicio web.
El uso de servidores intermedios para mejorar la escalabilidad hace necesario que los clientes de servicios web REST envíen peticiones completas e independientes, es decir, se deben enviar peticiones que incluyen todos los datos necesarios para cumplir el pedido, de manera que los componentes en los servidores intermedios puedan redireccionar y gestionar la carga sin mantener el estado localmente entre las peticiones.

Una petición completa e independiente hace que el servidor no tenga que recuperar ninguna información de contexto o estado al procesar la petición. Una aplicación o cliente de servicio web REST debe incluir dentro de la cabecera y del cuerpo HTTP de la petición todos los parámetros, contexto y datos que necesita el servidor para generar la respuesta. De esta manera, el no mantener estado mejora el rendimiento de los servicios web y simplifica el diseño e implementación de los componentes del servidor, ya que la ausencia de estado en el servidor elimina la necesidad de sincronizar los datos de la sesión con una aplicación externa.

Expone URIs con forma de directorios:
Desde el punto de vista del cliente de la aplicación que accede a un recurso, la URI determina qué tan intuitivo será el servicio web REST, y si el servicio va a ser utilizado tal como fue pensado al momento de diseñarlo. La tercera característica de los servicios web REST es justamente sobre las URIs.

Las URI de los servicios web REST deben ser intuitivas, hasta el punto que sea fácil adivinar. Pensamos en las URI como una interfaz auto-documentada que necesita de muy poca o ninguna explicación o referencia para que un desarrollador pueda comprender al que apunta, y los recursos derivados relacionados.

Una forma de lograr este nivel de usabilidad es definir URIs con una estructura al estilo de los directorios. Este tipo de URIs es jerárquica, con una única ruta raíz, y abriendo ramas a través de las subrutas para exponer las áreas principales del servicio. De acuerdo a esta definición, una URI no es sólo una cadena de caracteres delimitada por barras, sino más bien un árbol con subordinados y padres organizados como nodos. Por ejemplo, en un servicio de hilos de discusiones que tiene temas diversos, se podría definir una estructura de URI como esta:

http://www.miservicio.org/discusion/temas/ {tema}

La raíz, /discusión, tiene un nodo /temas como hijo. Bajo este nodo hay un conjunto de nombres de temas (como ser tecnología, actualidad, y más), cada uno de los cuales apunta un hilo. Dentro de esta estructura, resulta fácil recuperar hilos de discusión en tipear alguna cosa después de /temas/.

En algunos casos, la ruta a un recurso encaja muy bien dentro de la idea de “estructura de directorios”. Por ejemplo, tomemos algunos recursos organizados por fecha, que son muy prácticos de organizar usando una sintaxis jerárquica.

Transfiere XML, JavaScript Object Notation (JSON), o ambos:
La representación de un recurso en general refleja el estado actual del mismo y sus atributos al momento en que el cliente de la aplicación realiza la petición. La representación del recurso son simples “fotos” en el tiempo. Esto podría ser una representación de un registro de la base de datos que consiste en la asociación entre columnas y tags XML, donde los valores de los elementos en el XML contienen los valores de las filas. O, si el sistema tiene un modelo de datos, la representación de un recurso es una fotografía de los atributos de una de las cosas en el modelo de datos del sistema.

La última restricción al momento de diseñar un servicio web REST tiene que ver con el formato de los datos que la aplicación y el servicio se intercambian en las peticiones / respuestas. Aquí es donde realmente vale la pena mantener las cosas simples, legibles por personas, y conectadas.

Los objetos del modelo de datos generalmente se relacionan de alguna manera, y las relaciones entre los objetos del modelo de datos (los recursos) se reflejarán en la forma en que se representan en el momento de transferir los datos al cliente. En el servicio de hilos de discusión anterior, un ejemplo de una representación de un recurso conectado podría ser un tema de discusión raíz con todos sus atributos, y links embebidos en las respuestas al tema.

<discusion data=”{data}” tema=”{tema}”>
<comentario> {comentario} </comentario>
<respuestas>
<respuesta de = “gaz@mail.com “href =” /discusion/temas/{tema}/gaz “/>
<respuesta de = “gir@mail.com “href =” /discusion/temas/{tema}/gir “/>
</respuestas>
</discusion>

Conclusión: No siempre REST es la mejor opción. Está surgiendo como una alternativa para diseñar servicios web con menos dependencia en middleware propietario (por ejemplo, un servidor de aplicaciones), que su contraparte SOAP y los servicios basados en WSDL. De alguna manera, REST es la vuelta a la Web antes de la aparición de los grandes servidores de aplicaciones, ya que hace hincapié en los primeros estándares de Internet, URI y HTTP. XML sobre HTTP es una interfaz muy poderosa que permite que aplicaciones internas, como interfaces basadas en JavaScript asíncrono + XML (AJAX) puedan conectarse, ubicar y consumir recursos. De hecho, es justamente esta gran combinación con AJAX la que generó esta gran atención que ha tenido REST hoy en día.
Resulta muy flexible el poder exponer los recursos del sistema con un API REST, de manera de brindar datos a diferentes aplicaciones, formatos en diferentes maneras. REST ayuda a cumplir con los requerimientos de integración que son críticos para construir sistemas donde los datos deben poder combinar fácilmente y extender. Desde este punto de vista, los servicios REST se convierten en algo mucho más grande.

Serveis web a Mirth

Leer en castellano

Un servei web (Web Service en anglès) és una col·lecció de protocols i estàndards que serveix per intercanviar dades entre aplicacions. Diferents aplicacions de programari desenvolupades en llenguatges de programació diferents i executades sobre qualsevol plataforma poden utilitzar els serveis web per l’intercanvi de dades en una xarxa com Internet. Aquesta gran interoperatibilitat s’aconsegueix gràcies a l’adopció d’estàndards oberts.

El protocol usat per la transferència de missatges entre serveis web és SOAP, un protocol de comunicació dissenyat per intercanviar missatges en format XML en una xarxa d’ordinadors, normalment sobre el protocol HTTP.

Mirth disposa d’un web service listener ja definit al qual nomes cal definir-li el port,nom del servei i les interfícies que es volen escoltar, aquest web service permet rebre un paràmetre de tipus cadena de caràcters.

D’aquesta manera no es restringeix el contingut ja que al ser una cadena de caràcters no es valida i pot ser qualsevol tipus de dades. Mirth s’encarregarà de rebre el contingut del literal i parsejarlo al tipus  de dada definit en al origen com pot ser un XML.

Encara que aquest servei web per defecte no és gaire restrictiu i es pot usar en molts casos, és possible que sigui necessari modificar una major quantitat d’aspectes del  servei web més enllà dels mencionats anteriorment per això s’ha definit l’opció dels serveis web personalitzats (customs webservices).

Aquests webservices s’han de definir usant una classe Java que sigui subclasse  de AcceptMessage. Mitjançant anotacions es defineixen les seves propietats i mètodes.

Amb l’anotació @Webservice es defineixen els atributs del webservice, els principals són:

  • WsdlLocation: Defineix la ruta on es troba el wsdl que es publicarà.
  • TargetNamespace: Defineix el namespace del WSDL.
  • ServiceName: El nom del servei.
  • Name: El nom del wsdl:portType.
  • PortName: El valor del wsdl:portName.

A més de definir la configuració del webservice s’han de definir els mètodes del webservice. Els mètodes es defineixen com un mètode Java qualsevol però amb la particularitat que és necessari afegir l’anotació @WebMethod per indicar que és un mètode del webservice.

Un cop s’ha definit aquesta classe cal realitzar un arxiu Jar que contingui la classe i situar-lo a la carpeta custom-libs de Mirth. Seguidament és imprescindible fer referència aquesta classe en el listener tal com es pot veure a la següent imatge.

A més és necessari marcar Custom service i introduir el classpath de la classe que defineix el servei a Service Class Name.

Per últim per definir la resposta del servei s’ha d’afegir un objecte de la classe response al response map.

També serà imperatiu fer referencia a aquest element del response map al respond from de l’origen.

Seguint les directrius i instruccions que s’han presentat en aquesta entrada s’ha de poder crear gairebé qualsevol tipus de web service amb Mirth. Aconseguint així una major versatilitat al realitzar integracions que requereixin d’aquesta mena de serveis.

 

Llegir en català 

Un servicio web (Web Service en inglés) es una colección de protocolos y estándares que sirve para intercambiar datos entre aplicaciones. Diferentes aplicaciones de software desarrolladas en lenguajes de programación diferentes y ejecutadas sobre cualquier plataforma pueden utilizar los servicios web para el intercambio de datos en una red como Internet. Esta interoperatibilidad se consigue gracias a la adopción de estándares abiertos.

El protocolo usado para la transferencia de mensajes entre servicios web es SOAP, un protocolo de comunicación diseñado para intercambiar mensajes en formato XML en una red de ordenadores, normalmente sobre el protocolo HTTP.

Mirth dispone de un web service listener ya definido al cual solo hay que definirle el puerto,nombre del servicio y las interfaces que se quieren escuchar, este web service permite recibir un parámetro de tipo cadena de caracteres.

De este modo no se restringe el contenido puesto que al ser una cadena de caracteres no se valida y puede ser cualquier tipo de datos. Mirth se encargará de recibir el contenido del literal y parsearlo al tipo de dato definido en al origen como puede ser un XML.

Aunque este servicio web por defecto no es muy restrictivo y se puede usar en muchos casos, es posible que sea necesario modificar una mayor cantidad de aspectos de el servicio web más allá de los mencionats anteriormente por eso se ha definido la opción de los servicios web personalizados (customs webservices).

Estos servicios web se tienen que definir usando una clase Java que sea subclase de AcceptMessage. Mediante anotaciones se definen sus propiedades y métodos.

Con la anotación @Webservice se definen los atributos del servicio web, los principales son:

  • WsdlLocation: Define la ruta donde se encuentra el Wsdl que se publicará.
  • TargetNamespace: Define el namespace del Wsdl.
  • ServiceName: El nombre del servicio.
  • Name: El nombre del wsdl:portType.
  • PortName: El valor del wsdl:portName.

Además de definir la configuración del webservice se tienen que definir los métodos del webservice. Los métodos se definen como un método Java cualquiera pero con la particularidad que es necesario añadir la anotación @WebMethod para indicar que es un método del servicio.

Una vez se ha definido esta clase hay que realizar un archivo Jar que contenga la clase y situarlo en la carpeta custom-libs de Mirth. Seguidamente es imprescindible hacer referencia a esta clase en el listener tal como se puede ver a la siguiente imagen.

Además es necesario marcar Custom service e introducir el classpath de la clase que define el servicio en Service Class Name.

Por último para definir la respuesta del servicio se debe añadir un objeto de la clase response al response map.

También será imperativo hacer referencia a este elemento del response map en el respond from del origen.

Siguiendo las directrices e instrucciones que se han presentado en esta entrada se debe poder crear casi cualquier tipo de web service con Mirth. Consiguiendo así una mayor versatilidad al realizar integraciones que requieran de este tipo de servicios.