1. Обзор
В этом руководстве представлен краткий обзор тестирования REST API с помощью curl.
curl — это инструмент командной строки для передачи данных, который поддерживает около 22 протоколов, включая HTTP. Эта комбинация делает его очень хорошим специальным инструментом для тестирования наших REST-сервисов.
2. Параметры командной строки
curl поддерживает более 200 параметров командной строки . У нас может быть ноль или более из них для сопровождения URL-адреса в команде.
Прежде чем использовать его в наших целях, давайте взглянем на два, которые облегчат нам жизнь.
2.1. Подробный
Когда мы тестируем, рекомендуется включить подробный режим:
curl -v http://www.example.com/
В результате команды предоставляют полезную информацию, такую как разрешенный IP-адрес, порт, к которому мы пытаемся подключиться, и заголовки.
2.2. Выход
По умолчанию curl выводит тело ответа на стандартный вывод. Кроме того, мы можем предоставить опцию вывода для сохранения в файл:
curl -o out.json http://www.example.com/index.html
Это особенно полезно, когда размер ответа большой.
3. HTTP-методы с curl
Каждый HTTP-запрос содержит метод. Наиболее часто используемые методы — GET, POST, PUT и DELETE.
3.1. ПОЛУЧИТЬ
Это метод по умолчанию при совершении HTTP-вызовов с помощью curl . На самом деле показанные ранее примеры были обычными вызовами GET.
При запуске локального экземпляра службы на порту 8082 мы использовали бы что-то вроде этой команды для выполнения вызова GET:
curl -v http://localhost:8082/spring-rest/foos/9
Поскольку у нас включен подробный режим, мы получаем немного больше информации вместе с телом ответа:
* 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. ПОЧТА
Мы используем этот метод для отправки данных в службу-получатель, что означает, что мы используем параметр данных.
Самый простой способ сделать это — вставить данные в команду:
curl -d 'id=9&name=foreach' http://localhost:8082/spring-rest/foos/new
В качестве альтернативы мы можем передать файл, содержащий тело запроса, в параметр данных следующим образом:
curl -d @request.json -H "Content-Type: application/json"
http://localhost:8082/spring-rest/foos/new
Используя приведенные выше команды как есть, мы можем столкнуться с сообщениями об ошибках, подобными следующему:
{
"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"
}
Это связано с тем, что curl добавляет следующий заголовок по умолчанию ко всем запросам POST:
Content-Type: application/x-www-form-urlencoded
Это также то, что браузеры используют в простом POST. В нашем использовании мы обычно хотели бы настроить заголовки в зависимости от наших потребностей.
Например, если наша служба ожидает тип содержимого JSON, мы можем использовать параметр -H для изменения исходного запроса POST:
curl -d '{"id":9,"name":"foreach"}' -H 'Content-Type: application/json'
http://localhost:8082/spring-rest/foos/new
Командная строка Windows не поддерживает одинарные кавычки, как в Unix-подобных оболочках.
В результате нам пришлось бы заменить одинарные кавычки двойными, хотя мы пытаемся избегать их там, где это необходимо:
curl -d "{\"id\":9,\"name\":\"foreach\"}" -H "Content-Type: application/json"
http://localhost:8082/spring-rest/foos/new
Кроме того, когда мы хотим отправить несколько больший объем данных, обычно рекомендуется использовать файл данных.
3.3. ПОМЕЩАТЬ
Этот метод очень похож на POST, но мы используем его, когда хотим отправить новую версию существующего ресурса. Для этого мы используем опцию -X.
Без какого-либо упоминания о типе метода запроса curl по умолчанию использует GET; поэтому мы явно указываем тип метода в случае PUT:
curl -d @request.json -H 'Content-Type: application/json'
-X PUT http://localhost:8082/spring-rest/foos/9
3.4. УДАЛИТЬ
Опять же, мы указываем, что хотим использовать DELETE, используя параметр -X:
curl -X DELETE http://localhost:8082/spring-rest/foos/9
4. Пользовательские заголовки
Мы можем заменить заголовки по умолчанию или добавить собственные заголовки.
Например, чтобы изменить заголовок Host, мы делаем это:
curl -H "Host: com.foreach" http://example.com/
Чтобы отключить заголовок User-Agent, мы вводим пустое значение:
curl -H "User-Agent:" http://example.com/
Самый распространенный сценарий при тестировании — изменение заголовка Content-Type и Accept. Нам просто нужно добавить к каждому заголовку префикс -H:
curl -d @request.json -H "Content-Type: application/json"
-H "Accept: application/json" http://localhost:8082/spring-rest/foos/new
5. Аутентификация
Служба , требующая аутентификации , отправит обратно код ответа 401 — Unauthorized HTTP и соответствующий заголовок WWW-Authenticate.
Для базовой аутентификации мы можем просто встроить комбинацию имени пользователя и пароля в наш запрос, используя параметр пользователя :
curl --user foreach:secretPassword http://example.com/
Однако, если мы хотим использовать OAuth2 для аутентификации , нам сначала нужно получить access_token от нашей службы авторизации.
Ответ службы будет содержать access_token:
{
"access_token": "b1094abc0-54a4-3eab-7213-877142c33fh3",
"token_type": "bearer",
"refresh_token": "253begef-868c-5d48-92e8-448c2ec4bd91",
"expires_in": 31234
}
Теперь мы можем использовать токен в нашем заголовке авторизации:
curl -H "Authorization: Bearer b1094abc0-54a4-3eab-7213-877142c33fh3" http://example.com/
6. Заключение
В этой статье мы продемонстрировали использование минимальной функциональности curl для тестирования наших REST-сервисов. Хотя он может сделать намного больше, чем то, что здесь обсуждалось, для наших целей этого должно хватить.
Не стесняйтесь набирать curl -h в командной строке, чтобы проверить все доступные параметры. Служба REST, используемая для демонстрации, доступна здесь, на GitHub .