docs(api): update api description

Move the API description string to a separate variable to improve code readability. Add content to the (Open)API description summarized from general sections of the REST API documentation.
WeblateOrg · Jan 4, 2025 · 23ed331 · 23ed331
1 parent 486907e
commit 23ed331
Showing 1 changed file with 72 additions and 5 deletions.
diff --git a/weblate/api/spectacular.py b/weblate/api/spectacular.py
@@ -44,11 +44,7 @@ def get_spectacular_settings(
             "name": "GNU General Public License v3 or later",
             "url": "https://docs.weblate.org/en/latest/contributing/license.html",
         },
-        "DESCRIPTION": """
-The API is accessible on the ``/api/`` URL and it is based on [Django REST framework](https://www.django-rest-framework.org/).
-
-The OpenAPI specification is available as feature preview, feedback welcome!
-    """,
+        "DESCRIPTION": api_description,
         "EXTENSIONS_INFO": {
             "x-logo": {
                 "url": "/static/weblate.svg",
@@ -69,3 +65,74 @@ def get_spectacular_settings(
         settings["TOS"] = "/legal/terms/"
 
     return settings
+
+
+api_description = """
+This OpenAPI specification is offered as a feature preview, your feedback is welcome!
+
+---
+
+Weblate's REST API is based on [Django REST framework](https://www.django-rest-framework.org).
+You can interact with it on the `/api/` URL path by using the [Weblate Client](https://docs.weblate.org/en/latest/wlc.html) or any third-party REST client of your choice.
+
+## Authentication
+
+Authentication works with tokens placed in the `Authorization` HTTP request header:
+
+- Each user has a personal access token which they can get from their respective user profile. These tokens have the `wlu_` prefix.
+- It is possible to create project tokens whose access to the API is limited to operations to their associated project. These tokens have the `wlp_` prefix.
+
+Although some of the API operations are available without authentication,
+it is still recommended to authenticate your requests:
+
+- Operations such as `GET /api/users/` return an incomplete representation of the
+requested resources if the request has not been authenticated and authorized.
+- Anonymous requests are heavily rate limited, by default, to 100
+requests per day. On the other hand, authenticated requests are rate limited
+to 5000 requests per hour by default.
+
+## API rate limiting
+
+Rate limiting can be adjusted in the `settings.py` file; see [Throttling in Django REST framework documentation](https://www.django-rest-framework.org/api-guide/throttling/)
+for more details on how to configure it.
+
+In the Docker container, this can be configured with the [WEBLATE_API_RATELIMIT_ANON](https://docs.weblate.org/en/latest/admin/install/docker.html#envvar-WEBLATE_API_RATELIMIT_ANON) and the [WEBLATE_API_RATELIMIT_USER](https://docs.weblate.org/en/latest/admin/install/docker.html#envvar-WEBLATE_API_RATELIMIT_USER) environment variables.
+
+**Added in version 4.1:**
+HTTP response headers indicating status of rate-limiting.
+
+Those HTTP headers are:
+
+<table>
+    <thead>
+        <tr>
+            <td>Header name</td>
+            <td>Description</td>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>X-RateLimit-Limit</td>
+            <td>The maximum number of client requests allowed for a certain period of time, depending on whether the request is anonymous or authenticated.</td>
+        </tr>
+        <tr>
+            <td>X-RateLimit-Remaining</td>
+            <td>The remaining number of client requests allowed for the current timeframe.</td>
+        </tr>
+        <tr>
+            <td>X-RateLimit-Reset</td>
+            <td>The number of seconds until the rate limit is reset by the server.</td>
+        </tr
+    </tbody>
+</table>
+
+## Components and categories
+
+To access a component which is nested inside a [Category](https://docs.weblate.org/en/latest/admin/projects.html#category),
+you need to URL encode the category name into a component name separated with a slash.
+
+For example, usage placed in a `docs` category needs to be used as `docs%252Fusage`.
+In this case, the full URL could be:
+
+`https://weblate.example.com/api/components/hello/docs%252Fusage/repository/`
+"""