From 489ffcb7238d43155247b5e2d4ef8809b8cc7ba5 Mon Sep 17 00:00:00 2001
From: jld3103 <jld3103yt@gmail.com>
Date: Thu, 16 Nov 2023 19:20:49 +0100
Subject: [PATCH] feat(nextcloud): Add basic usage instructions

Signed-off-by: jld3103 <jld3103yt@gmail.com>
---
 packages/nextcloud/README.md | 38 ++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/packages/nextcloud/README.md b/packages/nextcloud/README.md
index 0e40adaf..6bf217db 100644
--- a/packages/nextcloud/README.md
+++ b/packages/nextcloud/README.md
@@ -22,6 +22,44 @@ dependency_overrides:
 ```
 You can either remove the `ref` or use a commit hash. It's not recommended to remove it, because then the version will be updated very often.
 
+## Usage
+
+### Authentication
+
+There are multiple ways to authenticate.  
+First there is HTTP Basic auth which works with the normal user credentials (e-mail and other identifiers also work):
+```dart
+final client = NextcloudClient(
+    Uri.parse('http://localhost'),
+    loginName: 'admin',
+    password: 'admin',
+);
+```
+
+Secondly there is Http Bearer auth which works with app passwords:
+```dart
+final client = NextcloudClient(
+    Uri.parse('http://localhost'),
+    loginName: 'admin',
+    appPassword: 'xxxxx-xxxxx-xxxxx-xxxx-xxxxx',
+);
+```
+
+Not all endpoints work with just HTTP Basic auth, so it is advised to use app passwords obtained either directly in the Web UI by the user or using the [login flow](https://docs.nextcloud.com/server/latest/developer_manual/client_apis/LoginFlow/index.html#login-flow-v2).  
+Some endpoints do not need any authentication at all or provide extended information when the request is optionally authenticated.
+
+### Endpoints
+
+It is not guaranteed that an API request will work unless the app is installed and enabled on the server (and has a supported version).  
+
+To get an easier overview of the available endpoints you can browse the [server OpenAPI documentation](https://docs.nextcloud.com/server/latest/developer_manual/_static/openapi.html), but be aware that the package might not be in sync with it.  
+Alternatively you can also go to https://pub.dev/documentation/nextcloud/latest (once the package has been republished at https://pub.dev/packages/nextcloud).
+
+The endpoints are grouped by app and most apps also group their endpoints again.
+They can be accessed using getters on the `NextcloudClient`.
+
+For an example checkout the [example](./example/example.dart).  
+
 ## Development
 
 Except for WebDAV all client code is generated using OpenAPI specifications which can be found in the `lib/src/api/` folder.