refactor(docs): api: core: write 'TicketSystem'

docs/api/core/ticket-system.md

 # Ticketsystem
 
-!!! todo
-    write usage api docs
+A `TicketSystem` object represents a connection definition to a space in an external ticket system.
+Part of this is a base URL, and some system specific identifier for e.g. a project on that system.
+If the access needs some kind of authentication,
+this has to be configured in this object on creation.
+
+## create new instance
+
+The constructor of `TicketSystem` is not publicly callable.
+Acquiring an instance has to be done either by passing an URI or using the builder mechanism.
+
+### by URI
+
+This library has a global definition, for how an URI has to start.
+The end of it is defined by each system specific implementation.
+
+!!! info "global URI definition"
+    `unifiedticketing:<system identifier>:<additional information>`  
+    _For system specific details look into the systems part of this docs_
+
+To instantiate a `TicketSystem` from an URI, call the static method `fromUri(String)`:
+
+```java
+TicketSystem ts = TicketSystem.fromUri(<uri>);
+```
+
+!!! warning
+    If the given String does not match the criteria for a valid URI,
+    or the system identifier is unknown, it throws an `AssertionException`
+
+### by builder
+
+The library has a builder mechanism defined to instantiate a new `TicketSystem` object, using fluent-api.
+To start it, call the static method `fromBuilder()`.  
+The returning object gives you all supported systems as choice,
+which then brings you to the system specific builder mechanism.
+
+At the end, you'll have to finish the building process with a call to `build()`.
+
+!!! warning
+    If not all mandatory information where given before calling `build()`,
+    it will throw an `AssertionException`
+
+## configuration options
+
+You can set configurations of two kinds:
+
+- simple boolean switches to enable/disable a behaviour/feature
+- string values
+
+To set a configuration, call the instance method `config`. It provides two signatures:
+
+- `config(TicketSystem.ConfigurationOption, boolean)`
+- `config(TicketSystem.ConfigurationOption, String)`
+
+??? abstract "currently available configuration options"
+    | ConfigurationOption  | type    | default | description                                                                                       |
+    | :------------------- | :------ | :------ | :------------------------------------------------------------------------------------------------ |
+    | RETURN_NULL_ON_ERROR | boolean | `false` | If true, don't throw exception on error, but return null or the calling object, if in fluent-api. |
+
+!!! warning
+    option `RETURN_NULL_ON_ERROR` is not fully implemented and tested yet.  
+    Expect it still throws Exceptions sometimes, but returns null/self also sometimes.
+## list tickets
+
+Tickets are requested by using the filter mechanism.
+To get _all_ Tickets just don't define any filters before calling `get()`.
+They are returned as `List<Ticket>`.
+
+??? warning "default pagination"
+    many systems have an implicit default pagination enabled,
+    which could block you from simply getting _all_ tickets.
+
+    you can ask the `TicketSystem` object, to tell you if it uses a default pagination:
+
+    ```java
+    ts.hasDefaultPagination();
+    ```
+
+!!! example "requesting tickets"
+    ```java
+    ts.find()
+        .setPage(1)
+        .setPageSize(10)
+        .get();
+    ```
+
+You can add various filter options, before finally calling `get()`.
+Each supported systems implementation is free to define special filter options.
+These are only callable, if your variable has the dedicated child-type.
+
+The globally available ones are listed below.
+They are marked `single` or `multi` types.
+A `single` typed filter will override previous values,
+whereas `multi` typed ones will be added to the previous values.
+
+| filter option method definition  | type     | description                                                                                                      |
+| :------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------- |
+| `isClosed()`                     | `single` | returns only tickets closed, or _considered_ closed by the system specific implementation                        |
+| `isOpen()`                       | `single` | returns only tickets open, or _considered_ open by the system specific implementation                            |
+| `setPage(int)`                   | `single` | page number of pagination to request                                                                             |
+| `setPageSize(int)`               | `single` | page size of request to paginate with                                                                            |
+| `withAssigneeId(String)`         | `multi`  | tickets with given assigneeId as assignee. <br/> On multiple calls ticket must have _ALL_ given ids as assignees |
+| `withAssigneeName(String)`       | `multi`  | same as assigneeId above                                                                                         |
+| `withDescriptionContain(String)` | `single` | substring the description has to contain                                                                         |
+| `withDescriptionMatch(String)`   | `single` | fully qualified regular expression, the whole description has to match                                           |
+| `withId(String)`                 | `multi`  | id a ticket must have. <br/> multiple calls keeps tickets matching _any_ of the set ids                          |
+| `withLabel(String)`              | `multi`  | label a ticket must have. <br/> Multiple calls a ticket must have _all_ given labels                             |
+| `withTitleContain(String)`       | `single` | substring the title has to contain                                                                               |
+| `withTitleMatch(String)`         | `single` | fully qualified regular expression, the whole title has to match                                                 |
+
+## get single ticket
+
+To request a single ticket the method `getTicketById` is provided,
+available with two signatures:
+- `getTicketById(String)`
+- `getTicketById(int)`
+
+The integer variant is just for convenience, if you have the id as number.
+It calls the String one with your number transformed.
+
+!!! example
+    ```java
+    Ticket t = ts.getTicketById("5");
+    ```
+
+## create new ticket
+
+The creation of a new Ticket is started by calling `createTicket()`.  
+This starts another fluid-api chain,
+in which you can set everything your new ticket should contain.
+The chain finishes calling `create()` at the end.
+
+!!! warning
+    if a mandatory information for ticket creation is not given,
+    prior calling `create()`,
+    an `AssertionException` is thrown.
+
+!!! example
+    ```java
+    Ticket t = ts.createTicket()
+        .title("some title")
+        .create();
+    ```
+
+Global available setters for ticket creation are:
+
+| method                                         | additional information                                                  |
+| :--------------------------------------------- | :---------------------------------------------------------------------- |
+| `assignees(String[])`                          | array of assignee identifiers, check system specific part, what to pass |
+| `description(String)`                          |                                                                         |
+| `labels(Set<String>)` <br/> `labels(String[])` |                                                                         |
+| `title(String)`                                |                                                                         |