Creando un API REST en Java (parte 1)

Creando un API REST en Java (parte 1)Sin lugar a duda, los servicios REST ya se han convertido en la principal tecnología para construir servicios, superando con creces a los servicios SOAP o comúnmente conocidos como Web Services. A pesar de que REST ya es visiblemente la tendencia en el desarrollo de servicios, sigue existiendo una gran discusión acerca de si SOAP es mejor que REST o al revés, sin embargo, no quiera tocar este tema ahora, pues no es el tema central de este artículo, para eso he creado el artículo “SOA vs REST” donde discutimos sobre estas dos tecnologías y sus ventajas y desventajas.

 

NOTA: Este artículo es parte de un tutorial completo para crear API REST con JAX-RS, si quieres ver el índice completo entra aquí.

 

Antes de comenzar, te cuento que puedes descargar el código completo en https://github.com/oscarjb1/blog-tutorial-jaxrs/tree/master/M%C3%A9todos%20HTTP/api

 

Configurando el proyecto

 

Dicho este, pasemos ahora si a implementar un API REST con Java, para esto, será indispensable crear un proyecto de tipo WEB en tu IDE favorito, en este caso, vamos a crear un “Dynamic web project” en Eclipse, para esto nos dirigimos a file -> new -> Other en el menú superior:

Seleccionamos la opción Dynamic web Project y presionamos Next para iniciar con la configuración de la aplicación:

Una vez aquí, escribimos “api” como nombre del proyecto y seleccionamos nuestro servidor de aplicaciones de preferencia, en nuestro caso, utilizamos Wildfly 11 pero podrías utilizar cualquier otro que tengas disponible. Finalmente, presionamos “Finish” para concluir con la creación del proyecto. El siguiente paso será convertir nuestro proyecto a un proyecto Maven, con la finalidad de administrar más fácilmente nuestras librerías. Para ello, nos posicionaremos sobre el proyecto creado y presionaremos “click derecho“ para abrir las opciones del proyecto, estando allí, nos dirigimos a configure -> convert to Maven Project, tras presionar esto, saldrá una ventana para configurar el proyecto, a lo que simplemente daremos finalizar.

Tras realizar los pasos anteriores deberás ver el proyecto tal y como se ve en la imagen anterior. Podrás observar una pequeña “M” en el ícono del proyecto, señal de que se trata de un proyecto Maven.

El siguiente paso es configurar las librerías de JavaEE y Wildfly con la finalidad de que estén disponibles en nuestro proyecto, por lo que tendremos que ir al archivo pom.xml y agregar las siguientes dos librerías:

 

Guardamos los cambios y tendremos que esperar un momento hasta que Eclipse descarga todas las dependencias necesarias, para esto, verás un indicador de progreso en la parte inferior derecha de Eclipse. Una vez que ha finalizado, estamos listos para empezar a desarrollar.

 

Iniciando el desarrollo

 

Lo primero que debemos de hacer para iniciar nuestra API REST es indicarle el Path base desde el cual estará respondiendo nuestra API. Este path corresponde a la URL a partir de la cual se expondrá nuestros servicios. Para lograr esto, será necesario crear una clase que extienda de “Application”, esta clase puede llamarse como sea y puede colocarse en cualquier paquete, lo único importante es que extienda de Application y defina la anotación @ApplicationPath. En nuestro caso crearemos la clase RestApplication en el package api.

 

 

Como podemos ver, hemos definido “/” como URL base, es decir que los servicios responderán a partir de la raíz del proyecto, pero tu podrías remplazarla por la URL base que más te guste, como por ejemplo “/api” o “/services”.

El siguiente paso será crear nuestro primer servicio, para lo cual deberemos crear una nueva clase, en este caso, crearemos la clase HelloWorldRest en el mismo paquete:

 

Como podrás observar, esta es una clase común y corriente pero que tiene algunas anotaciones, las cuales serán reconocidas por el servidor de aplicaciones para finalmente exponer el servicio, analicemos para que esta cada una de ellas.

La anotación @Path indica la URL en la cual responderá este servicio, cabe mencionar que esta anotación se puede poner a nivel de clase y método, en este caso, al estar a nivel de clase, afecta a todos los servicios que definamos, pero eso lo vamos a analizar más adelante.

Las siguientes dos anotaciones son para indicar que tipo de mensaje esperamos como entrada (consumes) y que tipo de mensaje vamos a responder (produces). En este caso, estamos indicando que esperamos JSON como entrada y que vamos a responder igualmente con JSON.

Finalmente, siguen los métodos, una clase puede tener más de un método, y cada método se puede exponer como un servicio independiente, sin embargo, en esta primera introducción empezaremos con uno. La anotación @GET le indica al servidor de aplicaciones que el método responde por el método GET únicamente. Adicional tenemos anotaciones para los demás métodos, como @POST, @PUT, @DELETE, etc. pero estos los estaremos analizando más adelante.

Podrás observar que el método responde con un tipo llamado Response, esta es una clase de utilidad que nos proporciona el API de JAX-RS para convertir fácilmente un objeto en un JSON en nuestro caso. Esta clase nos proporciona el método ok, el cual nos crea una respuesta con status 200, es decir, respuesta exitosa, la cual recibe el mensaje que queremos responder y el tipo de datos del mensaje, en nuestro caso JSON.

 

Probando nuestro Hello World

 

En este punto hemos terminado nuestro primer servicio, por lo que solo resta desplegarlo y probarlo. Para desplegarlo, basta con presionar el click derecho sobre el proyecto y presionar Run As -> Run on Server, presionar siguiente y finalizar.

Si la aplicación desplego correctamente, podremos probar el servicio en la URL http://localhost:8080/api-0.0.1-SNAPSHOT/helloworld, esta URL la podrás ejecutar directamente sobre el navegador:

En este punto te estarás preguntando como es que se generó esta URL, por lo que explico a continuación:

La URL se forma con la siguiente formula: <server_path>:<port>/<app_context>/<app_path>/<service_path>

La sección <server_path> y <port> corresponde al host del servidor y el puerto en el cual responde, esto corresponde a Wildfly.

La sección <app_context> corresponde a la URL base que nos asigna el servidor de aplicaciones cuando desplegamos.

La sección <app_path> fue la que definimos en la anotación @ApplicationPath. En nuestro caso, al definirla como “/” quiere decir que responderá a partir de la raíz del proyecto.

Finalmente, <service_path> corresponde a la URL definida en la anotación @Path, la cual se definió como “helloworld”.

 

Conclusiones

Hasta este punto hemos aprendido a crear un proyecto web y configurarlo para que responda a nuestras solicitudes como un API REST, por lo que en la siguiente sección de esta guía aprenderemos a utilizar los demás métodos (POST, DELETE, PUT) y aprenderemos a configurar nuestras URL para responder a URL más complejas, por lo que te invito a que te suscribas a mi blog para hacerte llegar las actualizaciones.

 

 

Artículos relacionados

Java 9 – análisis de las novedades Java 9 trae importantes novedades, pero todo sobre sale el sistema de módulos, para conocer todo acerca de java 9, te invito a veas mi articulo "J...
Java 8 – Interfaces funcionales Se le conoce como interface funcional a toda aquella interface que tenga solamente un método abstracto, es decir puede implementar uno o más métodos d...
Métodos HTTP (REST) Los métodos HTTP definen la acción que se realizará sobre un determinado recurso. Los métodos HTTP, también suelen ser llamados HTTP Verbs. Aunque el ...

Oscar Blancarte

Ideológico, Innovador y emprendedor, Padre, Tecnólogo y Autor, amante de la ciencia y la tecnología en todos sus colores y sabores. Arquitecto de software & Full Stack Developer con experiencia en la industria del desarrollo de software y la consultoría. Amante de la programación y el Ajedrez.

7 comentarios en “Creando un API REST en Java (parte 1)

  1. Esta bueno el artículo …, la gente debe analizar que en si los servicios web basados en SOAP y/ basados en REST, como parte de una arquitectura son buenos. Así mismo, diferenciar los enfoques que se tengan considerando el auge de los MicroServicios que en si son un tipo especial de servicios dentro de una arquitectura SOA, a nivel del inventario de servicios respectivamente.

    Como que me salí un poco del tema, jejeje el ejemplo está bien pero me hubiese gustado mejor verlo basado en un enfoque Topdown (definiendo tu contrato técnico apoyándote en: WADL, SWAGGER, RAML, etc), esto debido a que este enfoque es más mantenible a nivel de ambas partes: (Service Providers y Service Consumers), así la aplicación de estándares, principios, patrones y buenas practicas se pueden aplicar desde el Diseño respectivamente .

    Saludos Oscar.

    1. Lo que dices tiene sentido, desarrollar los servicios de Arriba abajo. En este articulo solo quise describir la forma de utilizar la tecnología, es por eso que no menciono nada de eso, pero me apunto el comentario para una segunda entrada.

      saludos.

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *