docs(api): update api description #13429
Conversation
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.
| 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]({get_doc_url(page='wlc')}) or any third-party REST client of your choice. | ||
|
|
||
| ## Authentication |
There was a problem hiding this comment.
This is already covered in OpenAPI, it could be definitely improved, but better to have it in standard location than in text:
There was a problem hiding this comment.
The OpenAPI spec allows to specify descriptions for the Security Scheme Object, so it should be possible to move information from the Authentication section in api_description to this other area of code.
I thought of moving this info in a separate PR. Do you prefer to do it in this one?
| requests per day. On the other hand, authenticated requests are rate limited | ||
| to 5000 requests per hour by default. | ||
|
|
||
| ## API rate limiting |
There was a problem hiding this comment.
This is already partly documented in response headers via add_middleware_headers:
There was a problem hiding this comment.
Good remark. I have moved their description to the respective Python module.
Move information about the HTTP response headers related to rate limit to variables representing those headers in the docs.py module.
for more information, see https://pre-commit.ci
|
This will need similar wrapping as introduced in #13546. Still, I'm not convinced that the description is the best place where to describe authentication and rate limiting. |
|
The authorization is mostly covered by the standard features since 22b6a05, so let's close this one as most of its content has been incorporated elsewhere. |
Proposed changes
Checklist
Other information
The rationale behind this change is to help the OpenAPI document stand on its own.
Relates to #12584