doc (webapi): Add list admin api (#1391)

dasch-swiss · Aug 13, 2019 · 1bfb624 · 1bfb624
1 parent ab33840
commit 1bfb624
Showing 1 changed file with 94 additions and 1 deletion.
diff --git a/docs/src/paradox/03-apis/api-admin/lists.md b/docs/src/paradox/03-apis/api-admin/lists.md
@@ -17,4 +17,97 @@ You should have received a copy of the GNU Affero General Public
 License along with Knora.  If not, see <http://www.gnu.org/licenses/>.
 -->
 
-# Lists Endpoint
+# Lists Endpoint
+
+## Endpoint Overview
+
+**List Operations:**
+
+- `GET: /admin/lists[?projectIri=<projectIri>]` : return all lists optionally filtered by project
+- `GET: /admin/lists/<listIri>` : return complete list with children
+- `POST: /admin/lists` : create new list
+- `POST: /admin/lists/<nodeIri>` : create new child node under the supplied parent node IRI
+- NOT IMPLEMENTED: `DELETE: /admin/lists/<listIri>` : delete list including children if not used
+- `GET: /admin/lists/infos/<listIri>` : return list information (without children)
+- `PUT: /admin/lists/infos/<listIri>` : update list information
+
+**List Node operations**
+
+- `GET: /admin/lists/nodes/<nodeIri>` : return list node information (without children)
+- NOT IMPLEMENTED: `POST: /admin/lists/nodes/<nodeIri>` : update list node information
+- NOT IMPLEMENTED: `DELETE: /admin/lists/nodes/<nodeIri>` : delete list node including children if not used
+
+## List Operations
+
+### Get lists
+
+ - Required permission: none
+ - Return all lists optionally filtered by project
+ - GET: `/admin/lists[?projectIri=<projectIri>]`
+
+### Get list
+
+ - Required permission: none
+ - Return complete list with children
+ - GET: `/admin/lists/<listIri>`
+
+
+### Create new list
+
+  - Required permission: SystemAdmin / ProjectAdmin
+  - POST: `/admin/lists`
+  - BODY:
+    ```
+    {
+        "projectIri": "someprojectiri",
+        "labels": [{ "value": "Neue Liste", "language": "de"}],
+        "comments": []
+    } 
+    ```
+
+### Create new child node
+
+  - Required permission: SystemAdmin / ProjectAdmin
+  - Appends a new child node under the supplied nodeIri. If the supplied nodeIri
+    is the listIri, then a new child node is appended to the top level. Children
+    are currently only appended.
+  - POST: `/admin/lists/<nodeIri>`
+  - BODY:
+    ```
+    {
+        "parentNodeIri": "nodeIri",
+        "projectIri": "someprojectiri",
+        "name": "first",
+        "labels": [{ "value": "New First Child List Node Value", "language": "en"}],
+        "comments": [{ "value": "New First Child List Node Comment", "language": "en"}]
+    }
+    ```
+
+### Get list's information
+
+ - Required permission: none
+ - Return list information (without children)
+ - GET: `/admin/lists/infos/<listIri>`
+ 
+### Update list's information
+
+ - Required permission: none
+ - Update list information
+ - PUT: `/admin/lists/infos/<listIri>`
+ - BODY:
+   ```
+   {
+       "listIri": "listIri",
+       "projectIri": "someprojectiri",
+       "labels": [{ "value": "Neue geönderte Liste", "language": "de"}, { "value": "Changed list", "language": "en"}],
+       "comments": [{ "value": "Neuer Kommentar", "language": "de"}, { "value": "New comment", "language": "en"}]
+   }
+   ```
+
+## List Node Operations
+
+### Get List Node Information
+
+ - Required permission: none
+ - Return list node information (without children)
+ - GET: `/admin/lists/nodes/<nodeIri>`