Tutorial: Jak testować API za pomocą cURL?

Gdybym miała podać, krótką definicję czym jest curl, zapewne napisałabym coś takiego:

cURL (Client for URLs) to konsolowe narzędzie, do transferu (odbierania i nadawania) danych przez Internet z wykorzystaniem wielu protokołów.

Krótko i zwięźle ✨

Dzisiaj ciężko sobie wyobrazić świat komunikacji po API bez curl’a. Niemal każda dokumentacja API, z którą się spotykam, zawiera przykłady użycia właśnie za pomocą tej komendy.

Curl dostarcza ujednolicony, niezależny od języka programowania, sposób na zaprezentowanie żądań i odpowiedzi http. Jest wygodnym narzędziem konsolowym, które umożliwia łatwe wysyłanie requestów HTTP/HTTPS, otrzymywanie danych w różnych formatach, a także automatyzację naszej pracy poprzez skrypty.

Niezależnie od tego, czy dopiero zaczynasz swoją przygodę z IT, czy jesteś bardziej zaawansowanym użytkownikiem, nauka korzystania z curl może oszczędzić Ci mnóstwo czasu i wysiłku przy pracy z REST API.

Więc weź filiżankę kawy i zanurzmy się w podstawach curl! ☕

Szybki przewodnik po używaniu CURL do zapytań HTTP / REST API

Spis treści:

• curl GET
• curl POST
• curl PUT
• curl PATCH
• curl DELETE
• Odczyt danych zapytania z pliku
• Zapis odpowiedzi zapytania do pliku

Otwórzcie terminal (linux / mac) lub wiersz poleceń i możemy zaczynać

GET request

Zapytania GET są najprostsze do wysłania. Jedyne co potrzebujemy to przekazać nasz URL jako argument komendy curl

curl https://api.restful-api.dev/objects

Dostaniemy odpowiedź:

[
   {
      "id": "1",
      "name": "Google Pixel 6 Pro",
      "data": {
         "color": "Cloudy White",
         "capacity": "128 GB"
      }
   },
   {
      "id": "2",
      "name": "Apple iPhone 12 Mini, 256GB, Blue",
      "data": null
   } ...
]

Możemy użyć curl z -v (skrót od --verbose), aby włączyć tryb pełnego opisu i zobaczyć więcej szczegółów zapytania.

curl -v https://api.restful-api.dev/objects

Spróbujmy przejść do innej ścieżki (path params), aby otrzymać obiekt o id wartości 1

curl https://api.restful-api.dev/objects/1

Możemy też korzystać z parametrów zapytania (query params) np.

curl https://api.restful-api.dev/objects?id=3

Przykład:
Przetestujmy na prawdziwym przykładzie, skorzystajmy ze API portalu dev.to, aby pobrać artykuły wg autora (mój profil wygląda tak dev.to/ritaly, ale chcę pobrać tylko wpisy)

curl https://dev.to/api/articles?username=ritaly

Zapytania z wieloma parametrami

Jeśli chcemy przekazać wiele parametrów, musimy je oddzielić poprzez ampersand (& – podobno polska nazwa to „etka” 😉).

➜ Documentacja API dev.to: https://developers.forem.com/api/v1

Jeszcze raz spójrzmy na dev.to API – chcemy połączyć 3 parametry

• tag: artykuły zawierające #devjournal
• top: najpopularniejsze artykuły z 5 dni
• per_page: limit 5 artykułów na stronę

curl  "https://dev.to/api/articles?tag=devjournal&top=5&per_page=5"

POST request

Otworzymy nowy obiekt z następującymi danymi jako body:

{
   "name": "Apple MacBook Pro 16",
   "data": {
      "year": 2019,
      "price": 2049.99,
      "CPU model": "Intel Core i9",
      "Hard disk size": "1 TB",
      "color": "silver"
   }
}

Wyślemy, curlem zapytanie POST:

curl -X POST https://api.restful-api.dev/objects \
-H 'Content-Type: application/json' \
-d '{"name":"Apple MacBook Pro 16","data":{"year":2019,"price":2049.99,"CPU model":"Intel Core i9","Hard disk size":"1 TB","color":"silver"}}'

W odpowiedzi zobaczymy utworzony nowy obiekt (skopiuj wartość jego id zachwilę nam się przyda).

Przyjrzyjmy się opcjom curl:

• -X <METHOD> – określa metodę HTTP zapytania np. POST, PUT, PATCH, DELETE
• -H – przekazuje niestandardowy nagłówek (curl używa application/x-www-form-urlencoded jako domyślny nagłówek typu Content-Type, my zmieniliśmy go na JSON)
• -d – dane / „ciało” (body) zapytania, zwane też API payload, jak wskazaliśmy w Content-Type, nasze dane są w formacie JSON
• -i, (--include) – nagłówki odpowiedzi mają się znaleźć w wyniku zapytania

Jeżeli chcesz wysłać więcej niż jeden nagłówek, możesz użyć opcji -H więcej niż raz np. dla zapytania GET /objects

curl -i \
     -H 'Connection: keep-alive' \
     -H 'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8' \
     -H 'Accept-Language: en-GB,en-US;q=0.8,en;q=0.6' \
     https://api.restful-api.dev/objects

Wykonując je z -v możemy przyjrzeć się jakie headery zostały zastosowane:

> GET /objects HTTP/2
> Host: api.restful-api.dev
> user-agent: curl/7.79.1
> connection: keep-alive
> accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
> accept-language: en-GB,en-US;q=0.8,en;q=0.6

Curl domyślnie identyfikuje się jako curl, widzimy to w polu user-agent. Możemy jednak na potrzeby naszych testów przedstawić się jako przeglądarka.

Dodajmy opcję -A (--user-agent), żeby podmienić klienta użytkownika (user agent)

curl -v \
     -H 'Connection: keep-alive' \
     -H 'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8' \
     -H 'Accept-Language: en-GB,en-US;q=0.8,en;q=0.6' \
-A 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/109.0.0.0 Safari/537.36' \
     https://api.restful-api.dev/objects

Wynik:

> GET /objects HTTP/2
> Host: api.restful-api.dev
> user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/109.0.0.0 Safari/537.36
> connection: keep-alive
> accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
> accept-language: en-GB,en-US;q=0.8,en;q=0.6

PUT request

Metoda PUT powoduje aktualizację obiektu poprzez zastąpienie istniejącego obiektu nowym. Musimy podać id obiektu, który chcemy zaktualizować.
Wyślij zapytanie PUT, wklej w miejsce:id id swojego obiektu.

curl -X PUT https://api.restful-api.dev/objects/:id \
     -H 'Content-Type: application/json' \
     -d '{"name":"Apple MacBook Pro 16","data":{"year":2022,"price":2399.99,"CPU model":"M1","Hard disk size":"1 TB","color":"space grey"}}'

PATCH request

Metoda PATCH również służy do aktualizacji obiektu, ale poprzez zmodyfikowanie wybranych pól rekordu, a nie zastąpienie całości.
Wyślij zapytanie PATCH (zastąp :id własną wartością).

curl -X PATCH https://api.restful-api.dev/objects/:id \
     -H 'Content-Type: application/json' \
     -d '{"name":"Fruity name"}'

Sprawdź rekord po zmianach:

curl https://api.restful-api.dev/objects/:id

DELETE request

Czas usunąć obiekt za pomocą metody DELETE. Metoda ta nie wymaga podania payloadu, ale musimy przekazać :id obiektu:

curl -X DELETE https://api.restful-api.dev/objects/:id

Twój obiekt został usunięty

Odczyt danych zapytania z pliku

Możemy odczytać payload z pliku i wykorzystać go jako body zapytania w curl, korzystając z opcji -d @requestfile, gdzie poprzedzamy nazwę pliku lub ścieżkę do pliku znakiem @.

curl -X POST https://api.restful-api.dev/objects \
     -d @request.json \
     -H "Content-Type: application/json"

plik request.json (musi istnieć w tej samej lokalizacji, w której wykonujemy zapytanie):

{
   "name": "Apple MacBook Pro 16",
   "data": {
      "year": 2019,
      "price": 1849.99,
      "CPU model": "Intel Core i9",
      "Hard disk size": "1 TB"
   }
}

Zapis odpowiedzi zapytania do pliku

Curl pozwala zapisać dane otrzymane w odpowiedzi zapytania, możemy użyć -o lub --output, po czym podać nazwę pliku.

curl https://api.restful-api.dev/objects -o response.json

Hurrrra! 🥳

Właśnie przeszliśmy podstawy korzystania z API za pomocą cURL i metod http.
Oczywiście możliwości jest znacznie więcej!

Ćwiczenia

Praktyka czyni mistrza, więc czym byłby tutorial bez zadań sprawdzających?

Zadanie 1

• Wykonaj zapytanie GET do JSONPlaceholder API. Zapoznaj się z dokumentacją i pobierz wszystkich użytkowników.
• Wykonaj zapytanie POST do API udostępniającego funkcjonalność tworzenia rekordu. Możesz ponownie użyć JSONPlaceholder API (POST /posts).
• Spróbuj wykonać żądanie PUT, aby zaktualizować istniejący zasób, użyj JSONPlaceholder API posts/1 .

Zadanie 2
Zapoznaj się z dokumentacją OpenWeatherMap API (zwróć uwagę, że musisz utworzyć darmowe konto, aby uzyskać swój klucz do API, później przekazywany w parametrze jako &appid={API key}).

• Wykonaj zapytanie GET do pogodowego API, aby pobrać dane dotyczące aktualnej prognozy pogody dla wybranego miasta (np. Poznań, Madryt, Londyn).
• Wykonaj zapytanie GET, które zwróci prognozę pogody 5-dniową dla Warszawy (zwróć uwagę, że możesz zapytanie wykonać na 2 sposoby podając długość i szerokość geograficzną, albo korzystając z wbudowanej opcji query params Built-in API request by city name).