docs: Add API docs for form extraction and filling API

Signed-off-by: Julius Härtl <jus@bitgrid.net>
2025-12-17 21:12:14 +01:00 · 2024-08-01 17:05:35 +02:00 · 2024-08-01 17:05:35 +02:00 · 670dfb26d4
commit 670dfb26d4
parent d4f0c2c8e5
1 changed files with 96 additions and 0 deletions
--- a/docs/form_filling_api.md
+++ b/docs/form_filling_api.md
@ -0,0 +1,96 @@
+<!--
+  - SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+  - SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+# Form extraction/filling API
+
+This API can be used to extract form data from files and to fill out forms of an existing file and store it.
+
+## Extract forms
+
+```
+GET /ocs/v2.php/apps/richdocuments/api/v1/template/fields/extract/{fileId}
+```
+
+### Parameters
+
+| Parameter   | Format                                 | Description                                |
+|-------------|----------------------------------------|--------------------------------------------|
+| fileId      | numeric                                | file id of the file to extract fields from |
+
+### Response data
+
+The response will be a list of fields where each field can have the following properties:
+
+| Parameter | Format  | Description                                                            |
+|-----------|---------|------------------------------------------------------------------------|
+| index     | string  | unique identifier for the field, to be used when filling out forms     |
+| content   | string  | current content of the field                                           |
+| type      | string  | one of `rich-text`, `checkbox`, `drop-down-list`, `picture`, `date`    |
+| alias     | ?string | User facing name of the field                                          | 
+| id        | ?string | Additional metadata when extracting open document format form controls | 
+| tag       | ?string | Additional metadata when extracting open document format form controls | 
+
+### Sample request
+```
+ curl https://nextcloud.local/ocs/v2.php/apps/richdocuments/api/v1/template/fields/extract/37526 \
+ 	-u "admin:admin"
+ 	-H "OCS-APIRequest: true" 
+```
+
+### Sample response
+
+```
+{
+  "ocs": {
+    "meta": {
+      "status": "ok",
+      "statuscode": 200,
+      "message": "OK"
+    },
+    "data": [
+      {
+        "index": "0",
+        "content": "Julius Härtl",
+        "type": "rich-text",
+        "alias": "Employee name",
+        "id": null,
+        "tag": null
+      },
+      {
+        "index": "1",
+        "content": "",
+        "type": "rich-text",
+        "alias": "Vacation date from",
+        "id": null,
+        "tag": null
+      }
+    ]
+  }
+}
+```
+
+## Fill out form fields
+
+Opening public share links requires federated editing being properly setup between the two servers.
+
+```
+POST /ocs/v2.php/apps/richdocuments/api/v1/template/fields/fill/{fileId}
+```
+
+### Parameters
+
+| Parameter   | Format                                 | Description                                                               |
+|-------------|----------------------------------------|---------------------------------------------------------------------------|
+| fileId      | numeric                                | file id of the source file to fill out                                    |
+| fields      | object<string, object{content: string}>  | Fields to be filled out with string content, identified by a string index as unique identifier |
+| destination | ?string                                | If passed the resulting file will be stored at this path                  | 
+
+```
+ curl https://admin:admin@nextcloud.local/ocs/v2.php/apps/richdocuments/api/v1/template/fields/fill/37526 \
+  	-H "Accept: application/json"
+ 	-H "Content-Type: application/json"
+ 	-X POST \
+ 	-H 'OCS-APIRequest: true' \  
+ 	--data '{"fields":{"0": {"content":"FooBar"}},"destination":"foobar.pdf"}'
+```