Tester une API REST avec curl

1. Vue d'ensemble

Ce tutoriel donne un bref aperçu du test d'une API REST à l'aide decurl.

curl is a command-line tool for transferring data and supports about 22 protocols including HTTP. Cette combinaison en fait un très bon outil ad hoc pour tester nos services REST.

Lectures complémentaires:

Test des API Web avec des collections Postman

Apprenez à créer une collection Postman pouvant tester une API REST

Un guide de REST-assuré

Explorez les bases de REST-assuré - une bibliothèque qui simplifie le test et la validation des API REST.

2. Options de ligne de commande

curl supports over 200 command-line options. 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 de définir le mode verbose sur:

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

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

2.2. Sortie

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

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

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

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. GET

C'est la méthode par défaut lors d'appels HTTP avec curl. En fait, les exemples présentés précédemment étaient des appels GET en clair.

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 http://localhost:8082/spring-rest/foos/9

Et puisque nous avons activé le mode détaillé, 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. POST

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

Le moyen le plus simple consiste à incorporer les données dans la commande:

curl -d 'id=9&name=example' http://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"
  http://localhost:8082/spring-rest/foos/new

En utilisant les commandes ci-dessus telles quelles, nous pouvons rencontrer des messages d'erreur tels que 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 demandes POST:

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

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

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

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

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

Par conséquent, nous devrons remplacer les guillemets simples par des guillemets doubles; leur échapper là où c'est nécessaire:

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

En outre, lorsque nous souhaitons envoyer une quantité de données légèrement supérieure, il est généralement préférable d’utiliser un fichier de données.

3.3. PUT

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 dans le cas de PUT:

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

3.4. EFFACER

De nouveau, nous spécifions que nous voulons utiliser DELETE en utilisant l'option -X:

curl -X DELETE http://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 de l'hôte, procédez comme suit:

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

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

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

Le scénario le plus courant lors des tests consiste à modifier les en-têtes Content-Type et Accept. Nous devrons simplement préfixer chaque en-tête avec l'option -H:

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

5. Authentification

Unservice that requires authentication renverrait un code de réponse HTTP 401 - Unauthorized et un en-tête WWW-Authenticate associé.

Pour l'authentification de base, nous pouvonssimply embed the username and password combination inside our request using the user option:

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

Cependant, si nous voulonsuse OAuth2 for authentication, nous devons d'abord obtenir le access_token de notre service d'autorisation.

La réponse du service contiendrait lesaccess_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 Authorization:

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

6. Conclusion

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

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

TOC

Tester une API REST avec curl