Add general documentation to API new documentation

src/api/public/apidocs-new/OBS-v2.10.50.yaml

@@ -8,7 +8,18 @@ tags:
   - name: Groups
 
 info:
-  description: Open Build Service API
+  description: |
+    The _Open Build Service API_ is a XML API.
+
+    To authenticate, use [HTTP basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) by passing the _Authorization_ header in the form of `Authorization: Basic <credentials>`.
+
+    There is no API versioning as there is no need for it right now.
+
+    Only rudimentary rate limiting is implemented, so please be gentle when using the API concurrently, especially with potentially expensive operations.
+    In case of abuse, we will limit/remove your access.
+
+    For command-line users, we recommend using [osc](https://github.com/openSUSE/osc) with its _api_ command to interact with the API.
+    It's as simple as this example: `osc api /about` (_about_ is one of the endpoints documented below)
   version: '2.10.50'
   title: Open Build Service API
   contact: