From 47df74adcaf65671716d07ab9da690bfa3454547 Mon Sep 17 00:00:00 2001 From: jld3103 Date: Thu, 16 Nov 2023 19:01:27 +0100 Subject: [PATCH 1/3] feat(nextcloud): Add example Signed-off-by: jld3103 --- packages/nextcloud/example/example.dart | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 packages/nextcloud/example/example.dart diff --git a/packages/nextcloud/example/example.dart b/packages/nextcloud/example/example.dart new file mode 100644 index 00000000..84a6076c --- /dev/null +++ b/packages/nextcloud/example/example.dart @@ -0,0 +1,13 @@ +import 'package:nextcloud/nextcloud.dart'; +import 'package:nextcloud/provisioning_api.dart'; + +Future main() async { + final client = NextcloudClient( + Uri.parse('http://localhost'), + loginName: 'admin', + password: 'admin', + ); + + final response = await client.provisioningApi.users.getCurrentUser(); + print(response.body.ocs.data.id); // Will print `admin` +} From 3dd1051af1c4e13edfdf235615ec23feffcf9700 Mon Sep 17 00:00:00 2001 From: jld3103 Date: Thu, 16 Nov 2023 19:01:46 +0100 Subject: [PATCH 2/3] chore(nextcloud): Remove outdated information from README.md Signed-off-by: jld3103 --- packages/nextcloud/README.md | 19 ++++--------------- 1 file changed, 4 insertions(+), 15 deletions(-) diff --git a/packages/nextcloud/README.md b/packages/nextcloud/README.md index b844ce55..0e40adaf 100644 --- a/packages/nextcloud/README.md +++ b/packages/nextcloud/README.md @@ -1,11 +1,8 @@ # nextcloud -A Nextcloud client written in Dart. +A Nextcloud API client written in Dart. -This client will become the replacement for https://github.com/provokateurin/dart-nextcloud at some point ([See](https://github.com/nextcloud/neon/issues/1)). - - -## Installing +## Installation In the future this code will be available at https://pub.dev/packages/nextcloud, but for now you have to include it via git in your pubspec.yaml: ```yaml @@ -27,13 +24,5 @@ You can either remove the `ref` or use a commit hash. It's not recommended to re ## Development -Except for WebDAV all client code is generated using OpenAPI specs which can be found in the `../../specs/` folder. -Templates for these OpenAPI specs are generated from the Nextcloud codebase to make development easier. - -To generate such a template take a look at `../../tool/generate-nextcloud.sh`. -After you have generated a template, you need to fill it out. Some endpoints can or have to be discarded. - -Then you start writing tests for the endpoints you added. -To easily inspect the responses for an endpoint, just set the `type` to `string` inside the `schema` blocks of the spec and let the output be printed in the tests. - -Sometimes you will have to look at the source code of Nextcloud, because the API is not always intuitive. Make sure to check if there is any API documentation that can help you. +Except for WebDAV all client code is generated using OpenAPI specifications which can be found in the `lib/src/api/` folder. +These OpenAPI specifications are [generated](https://github.com/nextcloud/openapi-extractor) from the PHP source code. From 489ffcb7238d43155247b5e2d4ef8809b8cc7ba5 Mon Sep 17 00:00:00 2001 From: jld3103 Date: Thu, 16 Nov 2023 19:20:49 +0100 Subject: [PATCH 3/3] feat(nextcloud): Add basic usage instructions Signed-off-by: jld3103 --- 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.