Tester une API REST avec curl

1. Vue d'ensemble

Ce didacticiel donne un bref aperçu du test d'une API REST à l'aide de curl.

curl est un outil de ligne de commande pour transférer des données et prend en charge environ 22 protocoles, y compris HTTP. Cette combinaison en fait un très bon outil ad hoc pour tester nos services REST.

2. Options de ligne de commande

curl prend en charge plus de 200 options de ligne de commande . Et nous pouvons en avoir zéro ou plus pour accompagner l'URL dans la commande.

Mais avant de l'utiliser à nos fins, jetons un coup d'œil à deux qui nous faciliteraient la vie.

2.1. Verbeux

Lorsque nous testons, c'est une bonne idée d'activer le mode verbeux:

curl -v //www.example.com/

En conséquence, les commandes fourniraient des informations utiles telles que l'adresse IP résolue, le port auquel nous essayons de nous connecter et les en-têtes.

2.2. Production

Par défaut, curl renvoie le corps de la réponse vers la sortie standard. En option, nous pouvons fournir l'option de sortie pour enregistrer dans un fichier:

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

Ceci est particulièrement utile lorsque la taille de la réponse est importante.

3. Méthodes HTTP avec Curl

Chaque requête HTTP contient une méthode. Les méthodes les plus couramment utilisées sont GET, POST, PUT et DELETE.

3.1. AVOIR

Il s'agit de la méthode par défaut lors des appels HTTP avec curl. En fait, les exemples précédemment présentés étaient des appels GET simples.

Lors de l'exécution d'une instance locale d'un service sur le port 8082, nous utiliserions quelque chose comme cette commande pour effectuer un appel GET:

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

Et puisque nous avons le mode verbeux activé, nous obtiendrions un peu plus d'informations avec le corps de la réponse:

* 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. PUBLIER

Nous utilisons cette méthode pour envoyer des données à un service récepteur. Et pour cela, nous utilisons l'option data.

La manière la plus simple de procéder consiste à incorporer les données dans la commande:

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

ou, passez un fichier contenant le corps de la requête à l'option data comme ceci:

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

En utilisant les commandes ci-dessus telles quelles, nous pouvons rencontrer des messages d'erreur comme le suivant:

{ "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" }

En effet, curl ajoute l'en-tête par défaut suivant à toutes les requêtes POST:

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

C'est également ce que les navigateurs utilisent dans un POST simple. Dans notre utilisation, nous souhaitons généralement personnaliser les en-têtes en fonction de nos besoins.

Par exemple, si notre service attend un type de contenu json, nous pouvons utiliser l'option -H pour modifier notre requête POST d'origine:

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

L'invite de commande Windows ne prend pas en charge les guillemets simples comme les shells de type Unix.

En conséquence, nous aurions besoin de remplacer les guillemets simples par des guillemets doubles; leur échapper là où c'est nécessaire:

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

En outre, lorsque nous voulons envoyer une quantité de données un peu plus grande, il est généralement judicieux d'utiliser un fichier de données.

3.3. METTRE

Cette méthode est très similaire à POST. Mais nous l'utilisons lorsque nous voulons envoyer une nouvelle version d'une ressource existante. Pour ce faire, nous utilisons l'option -X.

Sans aucune mention d'un type de méthode de requête, curl utilise par défaut GET. Par conséquent, nous mentionnons explicitement le type de méthode en cas de PUT:

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

3.4. EFFACER

Encore une fois, nous spécifions que nous voulons utiliser DELETE en utilisant l'option -X:

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

4. En-têtes personnalisés

Nous pouvons remplacer les en-têtes par défaut ou ajouter nos propres en-têtes.

Par exemple, pour changer l'en-tête Host, nous faisons ceci:

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

Pour désactiver l'en-tête User-Agent, nous mettons une valeur vide:

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

Le scénario le plus courant lors du test consiste à modifier l'en-tête Content-Type et Accept. Nous aurions juste à préfixer chaque en-tête avec l'option -H:

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

5. Authentification

Un service qui requiert une authentification renverrait un code de réponse HTTP 401 - Non autorisé et un en-tête WWW-Authenticate associé.

Pour l'authentification de base, nous pouvons simplement intégrer la combinaison nom d'utilisateur et mot de passe dans notre demande en utilisant l'option utilisateur :

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

Cependant, si nous voulons utiliser OAuth2 pour l'authentification, nous devons d'abord obtenir le access_token de notre service d'autorisation.

La réponse du service contiendrait le access_token:

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

Maintenant, nous pouvons utiliser le jeton dans notre en-tête d'autorisation:

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

6. Conclusion

Nous avons envisagé d'utiliser la fonctionnalité minimale de curl pour tester nos services REST. Bien qu'il puisse faire beaucoup plus que ce qui a été discuté ici, pour notre propos, cela devrait suffire.

N'hésitez pas à taper curl -h sur la ligne de commande pour découvrir toutes les options disponibles. Le service REST utilisé pour la démonstration est disponible ici sur GitHub.