diff --git a/docs/getting-started/rate-limiting.md b/docs/getting-started/rate-limiting.md new file mode 100644 index 0000000000000000000000000000000000000000..bc4fe7615723e50f102f7971b3217fd4789a6388 --- /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 99a689ee2532d3d378f121a341e60a20deeec8a4..35cb1a894f42386186a3314219bcf97b9975baf7 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 1a49d1338a9afc75bb5eba6bab38aea3b3c2ff1e..54be2affb5d7bff8f86880ee59aabfc5040de59b 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 0000000000000000000000000000000000000000..bc4fe7615723e50f102f7971b3217fd4789a6388 --- /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 99a689ee2532d3d378f121a341e60a20deeec8a4..35cb1a894f42386186a3314219bcf97b9975baf7 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 1a49d1338a9afc75bb5eba6bab38aea3b3c2ff1e..54be2affb5d7bff8f86880ee59aabfc5040de59b 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 1fa2d47a01a89071f8ba0301b6b5c523b9223ab9..c0a98f732219e1895ee4de3c1c782807af55f882 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"