From fba77bdf08c891dce4980410ecda0b8221c3f1de Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Julius=20H=C3=A4rtl?= <jus@bitgrid.net>
Date: Thu, 1 Aug 2024 17:05:35 +0200
Subject: [PATCH] docs: Add API docs for form extraction and filling API
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Julius Härtl <jus@bitgrid.net>
---
 docs/form_filling_api.md | 96 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 docs/form_filling_api.md

diff --git a/docs/form_filling_api.md b/docs/form_filling_api.md
new file mode 100644
index 0000000000..0da202038e
--- /dev/null
+++ 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, array{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"}'
+```