From a3254b583a740d1c16183aaa15946f1a9410d3f3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Markus=20Fl=C3=B6gel?= <markus.floegel@teleport.de>
Date: Tue, 23 Nov 2021 14:00:01 +0000
Subject: [PATCH] Dokumentation RateLimit-Headers
---
docs/getting-started/rate-limiting.md | 27 +++++++++++++++++++
.../sending/get-destination.mdx | 4 +++
docs/sidebar.js | 3 ++-
.../getting-started/rate-limiting.md | 27 +++++++++++++++++++
.../sending/get-destination.mdx | 4 +++
.../version-FIT-Connect_v1/sidebar.js | 3 ++-
.../version-FIT-Connect_v1-sidebars.json | 4 +++
7 files changed, 70 insertions(+), 2 deletions(-)
create mode 100644 docs/getting-started/rate-limiting.md
create mode 100644 versioned_docs/version-FIT-Connect_v1/getting-started/rate-limiting.md
diff --git a/docs/getting-started/rate-limiting.md b/docs/getting-started/rate-limiting.md
new file mode 100644
index 000000000..bc4fe7615
--- /dev/null
+++ b/docs/getting-started/rate-limiting.md
@@ -0,0 +1,27 @@
+# Rate Limiting
+
+FIT-Connect setzt sich aus mehreren Diensten zusammen. Für einige dieser Dienste ist der Durchsatz für Anfragen begrenzt, um abhängige Dienste nicht zu überlasten. Um dies zu realisieren wird in diesen Fällen ein Rate-Limiting angewandt, d.h. eine Begrenzung der Zahl der Anfragen an den Dienst in einem bestimmten Zeitintervall. Die genauen Begrenzungen werden je Dienst festgelegt.
+
+## Ratelimit-Headers
+Ist für einen Dienst das Rate Limiting eingerichtet, wird der Dienst in jeder Antwortnachricht entsprechende HTTP-Header senden. Die HTTP-Header folgen dem IETF-Draft [RateLimit Fields for HTTP](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers).
+
+### RateLimit-Limit
+Dieser Header gibt die aktuelle Begrenzung der Anfragen im momentanen Zeitfenster an. Falls mehrere Beschränkungen definiert sind, z.B. eine Beschränkung der Anfragen pro Sekunde und eine Beschränkung der Anfragen pro Minute, wird hier die Anzahl der zuerst eintretenden Beschränkung angegeben.
+
+### RateLimit-Remaining
+Dieser Header gibt die Anzahl der aktuell verfügbaren Anfragen im aktuellen Zeitfenster und der aktuell wirkenden Beschränkung zurück.
+
+### RateLimit-Reset
+Dieser Header gibt die Zeit in Sekunden an, wann das aktuelle Zeitfenster abläuft. Danach beginnt ein neues Zeitfenster für die aktuell wirkende Beschränkung.
+
+## Ãœberschreiten des Limits
+Wird eine Anfrage-Begrenzung überschritten, wird diese mit dem HTTP-Status-Code `429` beantwortet und kein Inhalt vom Dienst zurückgegeben. Die Anfrage sollte dann, unter Berücksichtigung des Headers `RateLimit-Reset` wiederholt werden.
+
+## Beispiel
+Beispiel für die in der HTTP-Response enthaltenen HTTP-Header:
+
+```yaml
+RateLimit-Limit: 20 # Begrenzung auf 20 Anfragen im aktuellen Zeitfenster
+RateLimit-Remaining: 3 # Es sind noch 3 Anfragen im aktuellen Zeitfenster möglich
+RateLimit-Reset: 14 # In 14 Sekunden wird das aktuelle Zeitfenster ablaufen und ein neues beginnen.
+```
diff --git a/docs/getting-started/sending/get-destination.mdx b/docs/getting-started/sending/get-destination.mdx
index 99a689ee2..35cb1a894 100644
--- a/docs/getting-started/sending/get-destination.mdx
+++ b/docs/getting-started/sending/get-destination.mdx
@@ -25,6 +25,8 @@ Das Ergebnis der Anfrage enthält daher neben der eigentlichen (Teil-)Ergebnisme
Die zurückgegebene Teilergebnismenge ist standardmäßig auf 100 Einträge limitiert und kann über den GET-Parameter `limit` auf maximal 500 Einträge erweitert werden.
Über den GET-Paramter `offset` können weitere Teilmengen der Ergebnismenge ermittelt werden.
+Der Endpunkt [/routes](../../apis/routing-api.mdx#get-/routes) ist auf die Anzahl von Anfragen in Zeitfenstern beschränkt. Es kann also vorkommen, das der Dienst einen `HTTP-Status-Code` `429` zurückliefert. Um diese Beschränkung auswerten zu können liefert der Endpunkt entspechende [RateLimit-Headers](../rate-limiting.md) bei jeder Antwork zurück.
+
Beispiele für das Ermitteln der benötigten Daten:
<Tabs
@@ -191,6 +193,8 @@ Die zurückgegebene Teilergebnismenge ist standardmäßig auf 100 Einträge limi
Die `id` eines Gebietes aus der Ergebnismenge kann im Endpunkt [/routes](../../apis/routing-api.mdx#get-/routes) als Identifikator (`areaId`) eines verwaltungspolitischen Gebietes verwendet werden.
+Der Endpunkt [/areas](../../apis/routing-api.mdx#get-/areas) ist auf die Anzahl von Anfragen in Zeitfenstern beschränkt. Es kann also vorkommen, das der Dienst einen `HTTP-Status-Code` `429` zurückliefert. Um diese Beschränkung auswerten zu können liefert der Endpunkt entspechende [RateLimit-Headers](../rate-limiting.md) bei jeder Antwork zurück.
+
Beispiele für die Suche:
diff --git a/docs/sidebar.js b/docs/sidebar.js
index 1a49d1338..54be2affb 100644
--- a/docs/sidebar.js
+++ b/docs/sidebar.js
@@ -28,6 +28,7 @@ module.exports = {
items: [
'getting-started/overview',
'getting-started/authentication',
+ 'getting-started/rate-limiting',
'getting-started/submission-structure',
'getting-started/metadata',
'getting-started/encryption',
@@ -51,7 +52,7 @@ module.exports = {
dirName: 'getting-started/receiving',
},
],
- },
+ }
],
},
// {
diff --git a/versioned_docs/version-FIT-Connect_v1/getting-started/rate-limiting.md b/versioned_docs/version-FIT-Connect_v1/getting-started/rate-limiting.md
new file mode 100644
index 000000000..bc4fe7615
--- /dev/null
+++ b/versioned_docs/version-FIT-Connect_v1/getting-started/rate-limiting.md
@@ -0,0 +1,27 @@
+# Rate Limiting
+
+FIT-Connect setzt sich aus mehreren Diensten zusammen. Für einige dieser Dienste ist der Durchsatz für Anfragen begrenzt, um abhängige Dienste nicht zu überlasten. Um dies zu realisieren wird in diesen Fällen ein Rate-Limiting angewandt, d.h. eine Begrenzung der Zahl der Anfragen an den Dienst in einem bestimmten Zeitintervall. Die genauen Begrenzungen werden je Dienst festgelegt.
+
+## Ratelimit-Headers
+Ist für einen Dienst das Rate Limiting eingerichtet, wird der Dienst in jeder Antwortnachricht entsprechende HTTP-Header senden. Die HTTP-Header folgen dem IETF-Draft [RateLimit Fields for HTTP](https://datatracker.ietf.org/doc/html/draft-ietf-httpapi-ratelimit-headers).
+
+### RateLimit-Limit
+Dieser Header gibt die aktuelle Begrenzung der Anfragen im momentanen Zeitfenster an. Falls mehrere Beschränkungen definiert sind, z.B. eine Beschränkung der Anfragen pro Sekunde und eine Beschränkung der Anfragen pro Minute, wird hier die Anzahl der zuerst eintretenden Beschränkung angegeben.
+
+### RateLimit-Remaining
+Dieser Header gibt die Anzahl der aktuell verfügbaren Anfragen im aktuellen Zeitfenster und der aktuell wirkenden Beschränkung zurück.
+
+### RateLimit-Reset
+Dieser Header gibt die Zeit in Sekunden an, wann das aktuelle Zeitfenster abläuft. Danach beginnt ein neues Zeitfenster für die aktuell wirkende Beschränkung.
+
+## Ãœberschreiten des Limits
+Wird eine Anfrage-Begrenzung überschritten, wird diese mit dem HTTP-Status-Code `429` beantwortet und kein Inhalt vom Dienst zurückgegeben. Die Anfrage sollte dann, unter Berücksichtigung des Headers `RateLimit-Reset` wiederholt werden.
+
+## Beispiel
+Beispiel für die in der HTTP-Response enthaltenen HTTP-Header:
+
+```yaml
+RateLimit-Limit: 20 # Begrenzung auf 20 Anfragen im aktuellen Zeitfenster
+RateLimit-Remaining: 3 # Es sind noch 3 Anfragen im aktuellen Zeitfenster möglich
+RateLimit-Reset: 14 # In 14 Sekunden wird das aktuelle Zeitfenster ablaufen und ein neues beginnen.
+```
diff --git a/versioned_docs/version-FIT-Connect_v1/getting-started/sending/get-destination.mdx b/versioned_docs/version-FIT-Connect_v1/getting-started/sending/get-destination.mdx
index 99a689ee2..35cb1a894 100644
--- a/versioned_docs/version-FIT-Connect_v1/getting-started/sending/get-destination.mdx
+++ b/versioned_docs/version-FIT-Connect_v1/getting-started/sending/get-destination.mdx
@@ -25,6 +25,8 @@ Das Ergebnis der Anfrage enthält daher neben der eigentlichen (Teil-)Ergebnisme
Die zurückgegebene Teilergebnismenge ist standardmäßig auf 100 Einträge limitiert und kann über den GET-Parameter `limit` auf maximal 500 Einträge erweitert werden.
Über den GET-Paramter `offset` können weitere Teilmengen der Ergebnismenge ermittelt werden.
+Der Endpunkt [/routes](../../apis/routing-api.mdx#get-/routes) ist auf die Anzahl von Anfragen in Zeitfenstern beschränkt. Es kann also vorkommen, das der Dienst einen `HTTP-Status-Code` `429` zurückliefert. Um diese Beschränkung auswerten zu können liefert der Endpunkt entspechende [RateLimit-Headers](../rate-limiting.md) bei jeder Antwork zurück.
+
Beispiele für das Ermitteln der benötigten Daten:
<Tabs
@@ -191,6 +193,8 @@ Die zurückgegebene Teilergebnismenge ist standardmäßig auf 100 Einträge limi
Die `id` eines Gebietes aus der Ergebnismenge kann im Endpunkt [/routes](../../apis/routing-api.mdx#get-/routes) als Identifikator (`areaId`) eines verwaltungspolitischen Gebietes verwendet werden.
+Der Endpunkt [/areas](../../apis/routing-api.mdx#get-/areas) ist auf die Anzahl von Anfragen in Zeitfenstern beschränkt. Es kann also vorkommen, das der Dienst einen `HTTP-Status-Code` `429` zurückliefert. Um diese Beschränkung auswerten zu können liefert der Endpunkt entspechende [RateLimit-Headers](../rate-limiting.md) bei jeder Antwork zurück.
+
Beispiele für die Suche:
diff --git a/versioned_docs/version-FIT-Connect_v1/sidebar.js b/versioned_docs/version-FIT-Connect_v1/sidebar.js
index 1a49d1338..54be2affb 100644
--- a/versioned_docs/version-FIT-Connect_v1/sidebar.js
+++ b/versioned_docs/version-FIT-Connect_v1/sidebar.js
@@ -28,6 +28,7 @@ module.exports = {
items: [
'getting-started/overview',
'getting-started/authentication',
+ 'getting-started/rate-limiting',
'getting-started/submission-structure',
'getting-started/metadata',
'getting-started/encryption',
@@ -51,7 +52,7 @@ module.exports = {
dirName: 'getting-started/receiving',
},
],
- },
+ }
],
},
// {
diff --git a/versioned_sidebars/version-FIT-Connect_v1-sidebars.json b/versioned_sidebars/version-FIT-Connect_v1-sidebars.json
index 1fa2d47a0..c0a98f732 100644
--- a/versioned_sidebars/version-FIT-Connect_v1-sidebars.json
+++ b/versioned_sidebars/version-FIT-Connect_v1-sidebars.json
@@ -36,6 +36,10 @@
"type": "doc",
"id": "version-FIT-Connect_v1/getting-started/authentication"
},
+ {
+ "type": "doc",
+ "id": "version-FIT-Connect_v1/getting-started/rate-limiting"
+ },
{
"type": "doc",
"id": "version-FIT-Connect_v1/getting-started/submission-structure"
--
GitLab