README.md 8.98 KB
Newer Older
Nane Kratzke's avatar
Nane Kratzke committed
1
# Lab 08: Request-Response-basierte Interaktion mit REST
Nane Kratzke's avatar
Nane Kratzke committed
2

Nane Kratzke's avatar
Nane Kratzke committed
3
4
[tutorial]: https://programminghistorian.org/en/lessons/creating-apis-with-python-and-flask

Nane Kratzke's avatar
Nane Kratzke committed
5
6
7
8
9
10
11
12
Web-APIs sind Schnittstellen, um Informationen und Anwendungsfunktionen Nutzern bzw. anderen Services über das Internet zugänglich zu machen. In diesem Lab:

- Erfahren Sie, was eine API ist und wann Sie eine verwenden sollten.
- Sie lernen, wie Sie eine REST-basierte Web-API erstellen.
- Sie lernen einige Prinzipien eines guten API-Designs kennen und wenden diese auf eine Beispiel-API an, die Buchmetadaten aus einer Datenbank bezieht.

## Inhalt

Nane Kratzke's avatar
Nane Kratzke committed
13
- [Lab 08: Request-Response-basierte Interaktion mit REST](#lab-08-request-response-basierte-interaktion-mit-rest)
Nane Kratzke's avatar
Nane Kratzke committed
14
15
16
17
  - [Inhalt](#inhalt)
  - [Vorbereitung](#vorbereitung)
  - [Übung 01: Bauen Sie einen einfachen REST-Service](#übung-01-bauen-sie-einen-einfachen-rest-service)
  - [Übung 02: Ergänzen Sie die Datenbank des Tutorials](#übung-02-ergänzen-sie-die-datenbank-des-tutorials)
Nane Kratzke's avatar
Deploy    
Nane Kratzke committed
18
  - [Übung 03: Ergänzen Sie nun eine grafische Auswertung](#übung-03-ergänzen-sie-nun-eine-grafische-auswertung)
Nane Kratzke's avatar
Nane Kratzke committed
19
20
21
  - [Verständnis- und Transferfragen](#verständnis--und-transferfragen)
  - [Links](#links)
  - [Was sollten Sie mitnehmen](#was-sollten-sie-mitnehmen)
Nane Kratzke's avatar
Nane Kratzke committed
22
23
24

## Vorbereitung

Nane Kratzke's avatar
Nane Kratzke committed
25
26
27
28
Sie benötigen auf Ihren lokalen Entwicklungsrechner:

- [Python 3](https://www.python.org/downloads)
- [Docker](https://www.docker.com/get-started)
Nane Kratzke's avatar
Nane Kratzke committed
29
- [Lens](https://k8slens.dev)
Nane Kratzke's avatar
Nane Kratzke committed
30
31
32

Führen Sie anschließend bitte folgende Schritte aus:

Nane Kratzke's avatar
Nane Kratzke committed
33
1. [Forken](https://git.mylab.th-luebeck.de/cloud-native/lab-rest/-/forks/new) Sie bitte dieses GitLab-Repository in Ihren GitLab-Namensraum.
Nane Kratzke's avatar
Nane Kratzke committed
34
35
36
37
38
2. Klonen Sie das in Schritt 1 geforkte Repository bitte anschließend auf ihrem lokalen Rechner (`git clone`).
3. Installieren Sie anschließend bitte lokal auf Ihrem Rechner die Kubernetes-IDE [Lens](https://k8slens.dev/).
4. Laden Sie sich Ihre `kubeconfig` Datei im [Moodle-Kurs](https://to-be-donex) herunter.
5. Starten Sie Lens und fügen Sie der IDE die kubeconfig Datei hinzu, um auf Ihren Cluster zugreifen zu können. Sie sollten dann Ihren Namespace in dem für Sie bereitgestellten K8S-Cluster sehen.
6. Erstellen Sie anschließend in Gitlab unter `Einstellungen -> Repository -> Bereitstellungstoken` für das in Schritt 1 geforkte Repository einen Bereitstellungstoken, um selbstgebaute Container Images deployen zu können.
Nane Kratzke's avatar
Nane Kratzke committed
39
40
41
42
    - **Name:** `Registry read access (deployment)`
    - **Username:** `image-registry` (bitte exakt so!)
    - **Scope:** `read-registry` (nicht mit read repository verwechseln!)
    - Klicken Sie anschließend auf Bereitstellungstoken erstellen und kopieren Sie sich dieses geheime Token in die Zwischenablage!
Nane Kratzke's avatar
Nane Kratzke committed
43
7. Hinterlegen Sie nun für Gitlab Build-Pipelines dieses geheime Token unter `Einstellungen -> CI/CD -> Variables (Aufklappen) -> ADD VARIABLE` als CI/CD-Variable.
Nane Kratzke's avatar
Nane Kratzke committed
44
45
46
47
    - **Key:** `CI_REGISTRY_TOKEN` (exakt so)
    - **Value:** Fügen Sie hier das geheime Token (Schritt 2) aus der Zwischenablage ein.
    - **Type:** `Variable` (nichts anderes)
    - **Flags:** Selektieren Sie `Mask Variable` damit das geheime Token in Log-Dateien maskiert wird.
Nane Kratzke's avatar
Nane Kratzke committed
48
8. Hinterlegen Sie in Ihrem geforkten GitLab-Repository nun die `kubeconfig`-Datei als CI-Environment-Variable mittels `Einstellungen -> CI/CI -> Variables (Aufklappen) -> ADD VARIABLE` (setzen Sie hierfür folgende Werte)
Nane Kratzke's avatar
Nane Kratzke committed
49
50
51
    - **Key:** `KUBECONFIG` (Exakt so eingeben)
    - **Value:** Inhalt der kubeconfig (z.B. mittels Copy-Paste aus Editor)
    - **Typ:** `File` (Auswählen, WICHTIG!!!)
Nane Kratzke's avatar
Nane Kratzke committed
52
9. Hinterlegen Sie die `kubeconfig`-Datei auch in Lens (`+` Button) um auf den Kubernetes Cluster von Ihrem lokalen Rechner aus zugreifen zu können.
Nane Kratzke's avatar
Nane Kratzke committed
53
54
55

## Übung 01: Bauen Sie einen einfachen REST-Service

Nane Kratzke's avatar
Nane Kratzke committed
56
Arbeiten Sie bitte dieses [Tutorial][tutorial] bis zum Punkt *API Design Principles* durch. Dieses Lab ist dafür vorbereitet.
Nane Kratzke's avatar
Nane Kratzke committed
57
58
59
60
61
62
63
64

- Implementieren Sie den Webservice in der Datei `api/api.py`.
- Ein Container kann mit `api/Dockerfile` gebaut werden.
- Die `.gitlab-ci.yml` ist so konfiguriert, das automatisch deployed werden kann.

Bevor Sie starten, prüfen Sie bitte lokal auf Ihrem Rechner, ob die Grundkonfiguration funktioniert.

```Bash
Nane Kratzke's avatar
Nane Kratzke committed
65
pip3 install flask
Nane Kratzke's avatar
Nane Kratzke committed
66
67
68
69
70
python3 api/api.py
```

Öffnen Sie dann [http://localhost:5000](http://localhost:5000) in einem Web-Browser. Sie sollten eine *"Distant Reading Archive"* Website sehen!

Nane Kratzke's avatar
Nane Kratzke committed
71
72
73
74
75
76
77
Prüfen Sie nun, ob Sie lokal einen Container bauen können.

```Bash
docker build api/ -t bookapi
docker run -p 8080:5000 bookapi
```

Nane Kratzke's avatar
Nane Kratzke committed
78
Öffnen Sie dann in einem Web-Browser die URL [http://localhost:8080](http://localhost:8080). Sie sollten dann erneut eine *"Distant Reading Archive"* Website sehen! Diesmal aus einem Container geliefert.
Nane Kratzke's avatar
Nane Kratzke committed
79
80
81

Committen und Pushen Sie nun diese Lösung in Git, um die Deployment Pipeline zu starten.

Nane Kratzke's avatar
Nane Kratzke committed
82
- Geben Sie in einem Lens Terminal nun `kubectl port-forward svc/api-svc 8888:5000` ein.
Nane Kratzke's avatar
Nane Kratzke committed
83
84
- Öffnen Sie dann in einem Web-Browser die URL [http://localhost:8888](http://localhost:8888). Sie sollten dann erneut eine *"Distant Reading Archive"* Website sehen! Diesmal jedoch aus Kubernetes geliefert.

Nane Kratzke's avatar
Deploy    
Nane Kratzke committed
85
86
87
88
89
90
91
Setzen Sie nun das [Tutorial][tutorial] bis zum Punkt *API Design Principles* fort. Sie sollten nun den Book-API-Service in Kubernetes deployen. Wenn Sie mittels `kubectl port-forward svc/api-svc 5000:5000` die Book-API auf Ihren lokalen Rechner forwarden, sollten Sie folgende Links ohne Fehlermeldung abfragen können.

- [http://127.0.0.1:5000/api/v1/resources/books?id=1](http://127.0.0.1:5000/api/v1/resources/books?id=1) (Das Buch mit der Id 1)
- [http://127.0.0.1:5000/api/v1/resources/books/all](http://127.0.0.1:5000/api/v1/resources/books/all) (Alle Bücher)

> __Hinweis:__
> Wenn Sie gar nicht weiter wissen, können Sie mit `cp cheat/api-ue1.py api/api.py` ggf. etwas abkürzen.
Nane Kratzke's avatar
Nane Kratzke committed
92

Nane Kratzke's avatar
Nane Kratzke committed
93
## Übung 02: Ergänzen Sie die Datenbank des Tutorials
Nane Kratzke's avatar
Nane Kratzke committed
94

Nane Kratzke's avatar
Deploy    
Nane Kratzke committed
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
Setzen Sie nun das [Tutorial][tutorial] fort. Arbeiten Sie erst den Punkt *API Design Principles* durch. Machen Sie dann daran, die Datenbank zu integrieren.

Das Tutorial stellt eine sqlite-Datenbank mit diversen Buchpublikationen zur Verfügung. Diese ist in diesem Repository schon unter `api/books.db` hinterlegt und muss durch Sie nicht herunter geladen werden.

Sie sollten dann einen größeren Buchbestand flexibler abfragen können.

- [http://127.0.0.1:5000/api/v1/resources/books/all](http://127.0.0.1:5000/api/v1/resources/books/all) 
- [http://127.0.0.1:5000/api/v1/resources/books?author=Connie+Willis](http://127.0.0.1:5000/api/v1/resources/books?author=Connie+Willis)
- [http://127.0.0.1:5000/api/v1/resources/books?author=Connie+Willis&published=1999](http://127.0.0.1:5000/api/v1/resources/books?author=Connie+Willis&published=1999) 
- [http://127.0.0.1:5000/api/v1/resources/books?published=2010](http://127.0.0.1:5000/api/v1/resources/books?published=2010)

> __Hinweis:__
> Wenn Sie gar nicht weiter wissen, können Sie mit `cp cheat/api-ue2.py api/api.py` ggf. etwas abkürzen.

## Übung 03: Ergänzen Sie nun eine grafische Auswertung

Ergänzen Sie nun eine Route `/api/v1/resources/books/plot`. Diese soll nun die grafische Auswertung der Satzlängen über die Jahre des [Tutorials][tutorial] liefern. Das Datenformat soll SVG (Scalable Vector Grafic) sein.

Wenn Sie mittels `kubectl port-forward svc/api-svc 5000:5000` die Book-API auf Ihren lokalen Rechner forwarden, sollten Sie für folgende URL

- [http://127.0.0.1:5000/api/v1/resources/books/plot](http://127.0.0.1:5000/api/v1/resources/books/plot)

in etwa folgende Darstellung im Browser erhalten.

![TOP-10](top-10.svg)

Nane Kratzke's avatar
Nane Kratzke committed
121
122
Danach scheinen die ersten Sätze in Science Fiction Romanen im Verlaufe der Jahrzehnte länger zu werden. Was immer das auch bedeuten mag.

Nane Kratzke's avatar
Deploy    
Nane Kratzke committed
123
> __Hinweis:__
Nane Kratzke's avatar
Nane Kratzke committed
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
> Wenn Sie gar nicht weiter wissen, können Sie mit `cp cheat/api-ue3.py api/api.py` ggf. etwas abkürzen.

## Verständnis- und Transferfragen

- Für welche Einsatzzwecke würden Sie Request-Resonse basierte Interaktion einsetzen?
- Erklären Sie bitte was eine gute designte API ausmacht.
- Erklären Sie bitte in eigenen Worten den REST-Ansatz.
- Erklären Sie den Zusammenhang zwischen REST und CRUD.
- Wurde URL oder DNS-Versionierung in diesem Beispiel verwendet?
- Auf welcher RMM-Ebene (Richardsen Maturity Model) würden Sie dieses Beispiel einordnen? 

## Links

- [Anatonomy of a URL](https://doepud.co.uk/blog/anatomy-of-a-url)
- [REST Paper](https://www.ics.uci.edu/~fielding/pubs/dissertation/top.htm) (the orginal PhD Thesis by Roy Fielding)
- [REST](https://de.wikipedia.org/wiki/Representational_State_Transfer) (Wikipedia)
- [Flask](https://flask.palletsprojects.com/en/1.1.x/) (Microframework für Python)

## Was sollten Sie mitnehmen

- Bei REST handelt es sich um ein Programmierparadigma, welches mit verschiedenen Mechanismen und Programmiersprachen implementiert werden kann.
- Üblich ist dabei die Verwendung von HTTP-Methoden in Verbindung mit auszuführenden CRUD-Aktionen auf Ressourcen.
- Die relativ engen Vorgaben von REST helfen gut strukturierte Dienste zu bauen, und unterstützen die Verwendung von Clean URLs.
- Mit Hilfe von Microframeworks (wie bspw. Flask) lassen sich REST-APIs oft unkompliziert erstellen.
Nane Kratzke's avatar
Nane Kratzke committed
148