docs: document pagination and the default base URL

README.md

@@ -46,9 +46,8 @@ Meteroid client = new Meteroid(
 ```
 
 Without an API key, the client reads `METEROID_API_KEY`, and `METEROID_BASE_URL`
-overrides the server of the API, `Meteroid.DEFAULT_BASE_URL`; explicit settings win. An API
-without a server has no default: the client then throws an `IllegalStateException` until one of
-them sets the base URL. The client is `AutoCloseable`: closing it
+overrides the server of the API, `Meteroid.DEFAULT_BASE_URL`; explicit settings win. It defaults to
+`https://api.meteroid.com`. The client is `AutoCloseable`: closing it
 releases its threads and connections. `httpClient(OkHttpClient)` shares your own OkHttp client
 (left open on close), and `addInterceptor` wraps every attempt for logging, caching or signing.
 Requests are logged through `System.Logger` (`com.meteroid`) at `DEBUG`, or at `INFO` with
@@ -110,6 +109,34 @@ response.requestId();
 response.body();
 ```
 
+## Pagination
+
+A list operation returns a page: the properties of the response body are its getters, next to
+its items and the way to the next page. Iterating a page yields every item from it on, fetching
+the next pages on demand:
+
+```java
+var page = client.addOns().list();
+page.paginationMeta();
+page.items();
+if (page.hasNextPage()) {
+    page = page.nextPage();
+}
+
+for (var addOn : client.addOns().list()) {
+    System.out.println(addOn);
+}
+
+for (var each : page.pages()) {
+    System.out.println(each.items().size());
+}
+
+client.async().addOns().list().thenCompose(first -> first.forEach(System.out::println));
+```
+
+`page.body()` is the response body as received, with the properties named like a member of the
+page (`items()`, `nextPage()`...).
+
 ## Errors
 
 Every exception the SDK throws is a `MeteroidException`:
@@ -135,7 +162,9 @@ try {
 
 Connection errors, timeouts, 408, 429 and 5xx responses are retried with jittered backoff,
 honoring `Retry-After` and `retry-after-ms` up to a minute (the backoff otherwise), when the method
-is idempotent or the request carries an `Idempotency-Key` (POST requests get one automatically).
+is idempotent or the request carries an `Idempotency-Key`.
 
 - Source: https://github.com/meteroid-oss/meteroid-java
 - License: Apache-2.0
+
+_Generated by [perseid](https://github.com/meteroid-oss/perseid)._