# API

- skodyfikowany, ustalony sposób komunikacji między dwiema lub więcej aplikacjami (Application Programming Interface).

To rodzaj umowy - "jeśli zadasz pytanie w ten sposób, dostaniesz ode mnie odpowiedź w takim formacie". Tę spisaną umowę możemy potraktować jako rodzaj instrukcji umożliwiającej uzyskanie potrzebnych nam danych z zewnętrznej aplikacji.

Tworzą je programiści / architekci tworzący daną aplikację.

## REST API

To zestaw wytycznych jak konstruować API w pewien określony sposób. Zawiera opis funkcji jakie API powinna realizować (GET, PUT, DELETE...) i sposób realizacji (np. brak przechowywania stanu pomiędzy zapytaniami, zapytania o ten sam zasób powinny wyglądać tak samo).

REST (Representational State Transfer) nie jest standardem / protokołem - to zestaw "luźnych" wytycznych np. nie ustala w jakim formacie będą dostarczane dane, może to być JSON, XML itd. (chociaż najczęściej spotyka się JSON-a).

Jeśli szukacie czegoś "sztywniejszego" należy sięgnąć po alternatywy np. SOAP (tam np. mamy sprecyzowane, że dane mają być wymieniane poprzez XML). Jednak ta elastyczność REST-a jest jednym z fundamentów sukcesu tego podejścia.

Aplikacje spełniające wymogi REST nazywane są RESTful.

Aby odczytać REST-owe API wysyłamy komunikat GET na odpowiedni adres pod którym jest przechowywany poszukiwany zasób (można to zrobić nawet w przeglądarce).

Jeśli chcemy uzyskać jakiś bardziej sprecyzowany zakres danych aplikacje je udostępniające zazwyczaj dają nam przynajmniej jedną z możliwości:

1. Inny adres dający nam te sprecyzowane dane
2. Parametry, które dodajemy do adresu lub w treści zapytania

Aby ułatwić testowanie / przeglądanie API powstała cała grupa aplikacji takich jak Postman , Insomnia, Hoppscotch itd.

## Hoppscotch.

To narzędzie umożliwiające nam testowanie i konstruowanie zapytań do API - bardzo ułatwia pracę, umożliwia przygotowanie działających zapytań przed ich implementacją w aplikacji.

- dostępny pod adresem **https://hoppscotch.io/**

[![](https://wiki.robisz.to/uploads/images/gallery/2024-10/scaled-1680-/image-1729511544308.png)](https://wiki.robisz.to/uploads/images/gallery/2024-10/image-1729511544308.png)![](../../prezentacje/resources/Pasted%20image%2020240915210500.png)

## CRUD

W kontekście API często pojawia się termin CRUD jako aplikacji realizującej 4 podstawowe funkcje:

1. Create (put/post - tworzenie)
2. Read (get - odczyt)
3. Update (post/put/patch - aktualizuj / modyfikuj)
4. Delete (delete - usuń)

# Python - requests

- służy do komunikacji z wykorzystaniem protokołu HTTP/HTTPS (czyli tego wykorzystywanego na stronach www)

https://requests.readthedocs.io/en/latest/

Jak zwykle zaczynamy od zaimportowania, po czym od razu możemy przystąpić do wysyłania zapytań - np. typu GET (czyli pobierz).

```python
import requests

odpowiedz = requests.get("https://api.frankfurter.app/latest")
```

Zwróci nam to obiekt typu **Response**. Jak go zdekodować?

Jeśli dostaliśmy JSON-a to np. tak:

```python
odczytana = odpowiedz.json()
```

Jeśli chcemy po prostu odczytać odpowiedz jako tekst to Response ma atrybut `.text`.

Jeśli zachodzi potrzeba dodania jakiś parametrów wystarczy np. przekazać odpowiednio skonstruowany słownik.

```python
parametry = {"key1" : "value1", "key2" : "value2"}

odpowiedz = requests.get("https://api.frankfurter.app/latest", params = parametry)
```

Podobnie jeśli chcemy dodać coś w nagłówku / body zapytania:

```python
naglowek = {"user-agent" : "my-app/0.0.1"}

odpowiedz = requests.get("https://api.frankfurter.app/latest", headers = naglowek)
```

## Hoppscotch - "gotowce"

Korzystając z narzędzi do testowania API możemy wspomóc się gotowym, wygenerowanym przez nie kodem:

[![](https://wiki.robisz.to/uploads/images/gallery/2024-10/scaled-1680-/image-1729512752127.png)](https://wiki.robisz.to/uploads/images/gallery/2024-10/image-1729512752127.png)


# Odnośniki

„3.12.5 Documentation”. Dostęp 18 sierpień 2024. [https://docs.python.org/3/](https://docs.python.org/3/).

Amazon Web Services, Inc. „What Is an API? - Application Programming Interface Explained - AWS”. Dostęp 15 wrzesień 2024. [https://aws.amazon.com/what-is/api/](https://aws.amazon.com/what-is/api/).

„API”. W _Wikipedia_, 13 wrzesień 2024. [https://en.wikipedia.org/w/index.php?title=API&oldid=1245469139](https://en.wikipedia.org/w/index.php?title=API&oldid=1245469139).

Dale, Kyran. _Data Visualization with Python and Javascript: Scrape, Clean, Explore & Transform Your Data_. Beijing Boston Farnham Sebastopol Tokyo, 2016.

„Hoppscotch • Open Source API Development Ecosystem”. Dostęp 15 wrzesień 2024. [https://hoppscotch.io/](https://hoppscotch.io/).

„What Is a REST API?” Dostęp 15 wrzesień 2024. [https://www.redhat.com/en/topics/api/what-is-a-rest-api](https://www.redhat.com/en/topics/api/what-is-a-rest-api).

„What Is a REST API? | IBM”, 19 październik 2021. [https://www.ibm.com/topics/rest-apis](https://www.ibm.com/topics/rest-apis).