refactor(docs): api: write 'index'

docs/api/index.md

 # Java-API
 
-!!! todo
-    - introductional text about library usage
-    - api docs structure explanation
-    - hint about no autogenerated JavaDoc, but manually written docs
+This is the API-Documentation,
+holding detailed information for each publicly available action you can do with each class.
+Below the structure of the library is explained and some generic examples are shown.
+## library structure
+
+The library is structured into three packages:
+
+1. `de.hftstuttgart.unifiedticketing.core`
+1. `de.hftstuttgart.unifiedticketing.exceptions`
+1. `de.hftstuttgart.unifiedticketing.systems`
+
+The core package contains the classes defining the generic API,
+to be implemented by each supported system.  
+The systems package contains a sub-package per supported system,
+which then holds the implementations of the core classes.  
+The exceptions package has some own exception types,
+used throughout the lib.
+
+For each package, this documentation provides a chapter in the navigation on the left.
+
+## examples
+
+!!! info
+    These examples are not specific to a certain system.
+    Therefore they can contain placeholders for system specific parts.
+    To get these parts, you'll have to go to the dedicated API-docs part.
+
+??? example "create TicketSystem instance"
+    __from builder:__
+    ```java
+    TicketSystem ts = TicketSystem.fromBuilder()
+        .<methods specifying connection details>
+        .build();
+    ```
+
+    __from uri:__
+    ```java
+    TicketSystem ts = TicketSystem.fromUri(<uri>);
+    ```
+
+??? example "searching tickets"
+    __without filters:__
+    ```java
+    ts.find().get();
+    ```
+
+    __only open tickets and explicit pagination:__
+    ```java
+    ts.find()
+        .isOpen()
+        .setPage(1)
+        .setPageSize(10)
+        .get();
+    ```
+
+??? warning "default pagination"
+    many systems have an implicit default pagination enabled,
+    which could block you from simply getting _all_ tickets.
+
+    !!! tip
+        you can ask the `TicketSystem` object, to tell you if it uses a default pagination:
+        ```java
+        ts.hasDefaultPagination();
+        ```