Prueba una API REST con curl

1. Información general

Este tutorial ofrece una breve descripción general de cómo probar una API REST con curl.

curl es una herramienta de línea de comandos para transferir datos y admite aproximadamente 22 protocolos, incluido HTTP. Esta combinación la convierte en una muy buena herramienta ad-hoc para probar nuestros servicios REST.

2. Opciones de la línea de comandos

curl admite más de 200 opciones de línea de comandos . Y podemos tener cero o más de ellos para acompañar la URL en el comando.

Pero antes de usarlo para nuestros propósitos, echemos un vistazo a dos que nos facilitarían la vida.

2.1. Verboso

Cuando estamos probando, es una buena idea configurar el modo detallado en:

curl -v //www.example.com/

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

2.2. Salida

De forma predeterminada, curl envía el cuerpo de respuesta a la salida estándar. Opcionalmente, podemos proporcionar la opción de salida para guardar en un archivo:

curl -o out.json //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. OBTENER

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

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

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

Y dado que tenemos activado el modo detallado, obtendríamos un poco más de información junto con el cuerpo de 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. ENVIAR

Usamos este método para enviar datos a un servicio de recepción. Y para eso usamos la opción de datos.

La forma más sencilla de hacer esto es incrustar los datos en el comando:

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

o, pase un archivo que contenga el cuerpo de la solicitud a la opción de datos como esta:

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

Al usar los comandos anteriores tal como están, podemos encontrarnos 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 predeterminado a todas las solicitudes POST:

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

Esto también es lo que usan los navegadores en un POST simple. En nuestro uso, generalmente querríamos personalizar los encabezados según nuestras necesidades.

Por ejemplo, si nuestro servicio espera json content-type, entonces podemos usar la opción -H para modificar nuestra solicitud POST original:

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

El símbolo del sistema de Windows no tiene soporte para comillas simples como los shells tipo Unix.

Como resultado, necesitaríamos reemplazar las comillas simples con comillas dobles; escapar de ellos donde sea necesario:

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

Además, cuando queremos enviar una cantidad de datos algo mayor, suele ser una buena idea utilizar un archivo de datos.

3.3. PONER

Este método es muy similar al POST. Pero lo usamos cuando queremos enviar una nueva versión de un recurso existente. Para hacer esto, usamos la opción -X.

Sin ninguna mención de un tipo de método de solicitud, curl usa de forma predeterminada GET. Por lo tanto, mencionamos explícitamente el tipo de método en caso de PUT:

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

3.4. ELIMINAR

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

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

4. Encabezados personalizados

Podemos reemplazar los encabezados predeterminados o agregar nuestros propios encabezados.

Por ejemplo, para cambiar el encabezado del Host, hacemos esto:

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

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

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

El escenario más habitual durante la prueba es cambiar el encabezado Content-Type y Accept. Solo tendríamos que anteponer cada encabezado con la opción -H:

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

5. Autenticación

Un servicio que requiere autenticación enviaría un 401 - Código de respuesta HTTP no autorizado y un encabezado WWW-Authenticate asociado.

Para la autenticación básica, simplemente podemos incrustar la combinación de nombre de usuario y contraseña dentro de nuestra solicitud usando la opción de usuario :

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

Sin embargo, si queremos usar OAuth2 para la autenticación, primero debemos 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" //example.com/

6. Conclusión

Analizamos el uso de la funcionalidad mínima de curl para probar nuestros servicios REST. Aunque puede hacer mucho más de lo que se ha discutido aquí, para nuestro propósito, esto debería ser suficiente.

Siéntase libre de escribir curl -h en la línea de comando para ver todas las opciones disponibles. El servicio REST utilizado para la demostración está disponible aquí en GitHub.