1. Overview

Este tutorial ofrece una breve descripción sobre cómo probar una API REST utilizando curl. curl es una herramienta de línea de comandos para transferir datos y es compatible con aproximadamente 22 protocolos, incluido HTTP. Esta combinación la convierte en una herramienta muy útil y ad-hoc para probar nuestros servicios REST.

2. Opciones de Línea de Comandos

curl admite más de 200 opciones de línea de comandos. Podemos tener cero o más de ellas para acompañar la URL en el comando. Antes de utilizarla para nuestros fines, veamos dos opciones que facilitarán nuestra vida.

2.1. Verbose

Cuando estamos probando, es buena idea activar el modo detallado.

curl -v http://www.example.com/

Como resultado, estos comandos proporcionan información útil como la dirección IP resuelta, el puerto al que intentamos conectarnos y los encabezados relevantes.

2.2. Output

De forma predeterminada, curl muestra el cuerpo de la respuesta en la salida estándar. Además, podemos proporcionar la opción de salida para guardar en un archivo:

curl -o out.json http://www.example.com/index.html

Esto es especialmente útil cuando el tamaño de la respuesta es grande.

3. Métodos HTTP Con curl

Cada solicitud HTTP contiene un método. Los métodos más utilizados son GET, POST, PUT y DELETE.

3.1. GET

Este es el método predeterminado al hacer llamadas HTTP con curl. De hecho, los ejemplos anteriormente mostrados eran llamadas GET simples.

Al ejecutar una instancia local de un servicio en el puerto 8082, usaríamos un comando como este para hacer una llamada GET:

curl -v http://localhost:8082/spring-rest/foos/9

Dado que tenemos el modo detallado activado, obtenemos más información junto con el cuerpo de la respuesta:

*   Trying ::1...
* TCP_NODELAY set
* Connected to localhost (::1) port 8082 (#0)
> GET /spring-rest/foos/9 HTTP/1.1
> Host: localhost:8082
> User-Agent: curl/7.60.0
> Accept: */*
>
< HTTP/1.1 200 
< X-Application-Context: application:8082
< Content-Type: application/json;charset=UTF-8
< Transfer-Encoding: chunked
< Date: Sun, 15 Jul 2018 11:55:26 GMT
<
{
  "id" : 9,
  "name" : "TuwJ"
}
* Connection #0 to host localhost left intact

3.2. POST

Usamos este método para enviar datos a un servicio receptor, lo que significa que utilizamos la opción data. La forma más sencilla de hacer esto es incrustando los datos en el comando:

curl -d 'id=9&name=baeldung' http://localhost:8082/spring-rest/foos/new

Alternativamente, podemos pasar un archivo que contenga el cuerpo de la solicitud a la opción data:

curl -d @request.json -H "Content-Type: application/json" http://localhost:8082/spring-rest/foos/new

Si usamos los comandos como están, podríamos toparnos con mensajes de error como el siguiente:

{
  "timestamp" : "15-07-2018 05:57",
  "status" : 415,
  "error" : "Unsupported Media Type",
  "exception" : "org.springframework.web.HttpMediaTypeNotSupportedException",
  "message" : "Content type 'application/x-www-form-urlencoded;charset=UTF-8' not supported",
  "path" : "/spring-rest/foos/new"
}

Esto se debe a que curl agrega el siguiente encabezado por defecto a todas las solicitudes POST:

Content-Type: application/x-www-form-urlencoded

Esto es también lo que utilizan los navegadores en una POST simple. En nuestro uso, generalmente queremos personalizar los encabezados según nuestras necesidades. Por ejemplo, si nuestro servicio espera un tipo de contenido JSON, podemos usar la opción -H para modificar nuestra solicitud POST original:

curl -d '{"id":9,"name":"baeldung"}' -H 'Content-Type: application/json' http://localhost:8082/spring-rest/foos/new

El símbolo de comillas simples no está soportado por el símbolo de sistema de Windows, así que necesitaríamos reemplazar las comillas simples con comillas dobles, escapando donde sea necesario:

curl -d "{\"id\":9,\"name\":\"baeldung\"}" -H "Content-Type: application/json" http://localhost:8082/spring-rest/foos/new

Además, cuando queremos enviar una cantidad algo mayor de datos, generalmente es buena idea usar un archivo de datos.

3.3. PUT

Este método es muy similar a POST, pero se utiliza cuando queremos enviar una nueva versión de un recurso existente. Para hacerlo, utilizamos la opción -X.

Sin mencionar un tipo de método de solicitud, curl utilizará GET de forma predeterminada; por lo tanto, debemos mencionar explícitamente el tipo de método en el caso de PUT:

curl -d @request.json -H 'Content-Type: application/json' -X PUT http://localhost:8082/spring-rest/foos/9

3.4. DELETE

Nuevamente, especificamos que queremos usar DELETE utilizando la opción -X:

curl -X DELETE http://localhost:8082/spring-rest/foos/9

4. Encabezados Personalizados

Podemos reemplazar los encabezados predeterminados o añadir nuestros propios encabezados. Por ejemplo, para cambiar el encabezado Host, hacemos esto:

curl -H "Host: com.baeldung" http://example.com/

Para desactivar el encabezado User-Agent, simplemente proporcionamos un valor vacío:

curl -H "User-Agent:" http://example.com/

El escenario más común al probar es cambiar el encabezado Content-Type y el encabezado Accept. Solo tenemos que añadir cada encabezado con la opción -H:

curl -d @request.json -H "Content-Type: application/json" -H "Accept: application/json" http://localhost:8082/spring-rest/foos/new

5. Autenticación

Un servicio que requiere autenticación devolvería un código de respuesta HTTP 401 – no autorizado, junto con un encabezado WWW-Authenticate. Para autenticación básica, podemos incluir simplemente la combinación de nombre de usuario y contraseña dentro de nuestra solicitud usando la opción user:

curl --user baeldung:secretPassword http://example.com/

Sin embargo, si queremos usar OAuth2 para autenticación, primero necesitaremos obtener el access_token de nuestro servicio de autorización. La respuesta del servicio contendría el access_token:

{
  "access_token": "b1094abc0-54a4-3eab-7213-877142c33fh3",
  "token_type": "bearer",
  "refresh_token": "253begef-868c-5d48-92e8-448c2ec4bd91",
  "expires_in": 31234
}

Ahora podemos usar el token en nuestro encabezado de Autorización:

curl -H "Authorization: Bearer b1094abc0-54a4-3eab-7213-877142c33fh3" http://example.com/

6. Conclusion

En este artículo, demostramos cómo usar las funcionalidades más básicas de curl para probar nuestros servicios REST. Aunque puede hacer mucho más de lo que hemos discutido aquí, para nuestros propósitos, esto debería ser suficiente. Recuerda que la práctica es clave al trabajar con APIs y herramientas de línea de comandos. Familiarízate con los métodos, encabezados y opciones de curl para que puedas realizar pruebas más eficientes y efectivas en tus aplicaciones JAVA.

Consejo práctico para programadores: siempre asegúrate de leer la documentación de la API que estás probando y de realizar pruebas exhaustivas con diferentes métodos HTTP y formatos de datos. Esto no solo te ayudará a identificar posibles errores, sino que también mejorará la comprensión general de cómo funciona la API que estás utilizando.