Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
refactor(lists+groups): improve value objects + remove new lists impl…
…ementation (DEV-160) (#1932)

* refactor group create payload

* separate group route value object

* add group iri value object

* use project IRI in group create patload + add group value object error messages &  test

* updated groups value objects and tests

* add value objects to groups update payload

* move optional params to value objects + replace either by zio.Validation

* refactor(list): replace Either with zio.Validation + move option to value objects

* refactor projectIri value object

* fix node creation

* add validation to payloads creation in lists and groups

* remove doubled checks and related tests

* disable new list route + separate NodeApiRequestADM to root & child

* list route factory + new list route implementation

* refactor list naming

* make parentNodeIri required for ListChildNodeCreatePayloadADM

* fix tests

* refactor lists get methods

* update lists docs

* fix update single lists properties + groups cleanup

* fix client-test-data

* bring back GET methods

* fix file extension

* fix testdata
  • Loading branch information
mpro7 committed Nov 17, 2021
1 parent ca0c532 commit 24e34dd
Show file tree
Hide file tree
Showing 44 changed files with 1,238 additions and 3,221 deletions.
2 changes: 1 addition & 1 deletion docs/03-apis/api-admin/groups.md
Expand Up @@ -87,7 +87,7 @@ hasProjectRestrictedGroupAdminPermission (for this group)
- PUT: `/admin/groups/<groupIri>/status`
- BODY:

```
```json
{
"status": false
}
Expand Down
1 change: 0 additions & 1 deletion docs/03-apis/api-admin/index.md
Expand Up @@ -13,6 +13,5 @@ The Knora admin API makes it possible to administer Knora projects, users, user
- [Projects Endpoint](projects.md)
- [Groups Endpoint](groups.md)
- [Lists Endpoint](lists.md)
- [New Lists Endpoint](lists_new-list-admin-routes_v1.md)
- [Permissions Endpoint](permissions.md)
- [Stores Endpoint](stores.md)
264 changes: 103 additions & 161 deletions docs/03-apis/api-admin/lists.md
Expand Up @@ -10,23 +10,23 @@
**List Item Operations:**

- `GET: /admin/lists[?projectIri=<projectIri>]` : return all lists optionally filtered by project
- `GET: /admin/lists/<listItemIri>` : return complete list with all children if IRI of the list (i.e. root node) is given.
If IRI of the child node is given, return the node with its immediate children.
- `GET: /admin/lists/<listItemIri>` : return complete list with all children if IRI of the list (i.e. root node) is given
If IRI of the child node is given, return the node with its immediate children
- `GET: /admin/lists/infos/<listIri>` : return list information (without children)
- `GET: /admin/lists/nodes/<nodeIri>` : return list node information (without children)
- `GET: /admin/lists/<listIri>/info` : return list basic information (without children)

- `POST: /admin/lists` : create new list
- `POST: /admin/lists/<parentNodeIri>` : create new child node under the supplied parent node IRI

- `PUT: /admin/lists/<listItemIri>` : update node information (root or child.)
- `PUT: /admin/lists/<listItemIri>/name` : update the name of the node (root or child).
- `PUT: /admin/lists/<listItemIri>/labels` : update labels of the node (root or child).
- `PUT: /admin/lists/<listItemIri>/comments` : update comments of the node (root or child).
- `PUT: /admin/lists/<listItemIri>` : update node information (root or child)
- `PUT: /admin/lists/<listItemIri>/name` : update the name of the node (root or child)
- `PUT: /admin/lists/<listItemIri>/labels` : update labels of the node (root or child)
- `PUT: /admin/lists/<listItemIri>/comments` : update comments of the node (root or child)
- `PUT: /admin/lists/<nodeIri>/position` : update position of a child node within its current parent or by changing its
parent node.
parent node

- `DELETE: /admin/lists/<listItemIri>` : delete a list (i.e. root node) or a child node and
all its children, if not used
- `DELETE: /admin/lists/<listItemIri>` : delete a list (i.e. root node) or a child node and all its children, if not used

## List Item Operations

Expand All @@ -39,20 +39,39 @@ all its children, if not used
### Get list

- Required permission: none
- Return complete `list` including basic information of the list, `listinfo`, and all its children.
- Return complete `list` (or `node`) including basic information of the list (or child node), `listinfo` (or `nodeinfo`),
and all its children
- GET: `/admin/lists/<listIri>`

### Get list's information

- Required permission: none
- Return list information, `listinfo` (without children).
- GET: `/admin/lists/infos/<listIri>`

### Get list node Information

- Required permission: none
- Return node information, `nodeinfo`, (without children).
- GET: `/admin/lists/nodes/<nodeIri>`

### Get list's information (merged)

- Required permission: none
- Return list (or node) basic information, `listinfo` (or `nodeinfo`), without its children
- GET: `/admin/lists/<listIri>/info`

### Create new list

- Required permission: SystemAdmin / ProjectAdmin
- Required fields: `projectIri`, `labels`, `comments`
- POST: `/admin/lists`
- BODY:

```json
{
"projectIri": "someprojectiri",
"labels": [{ "value": "Neue Liste", "language": "de"}],
"labels": [{ "value": "New list", "language": "en"}],
"comments": []
}
```
Expand All @@ -64,8 +83,8 @@ Additionally, each list can have an optional custom IRI (of [Knora IRI](../api-v
"id": "http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
"projectIri": "http://rdfh.ch/projects/0001",
"name": "a new list",
"labels": [{ "value": "Neue Liste mit IRI", "language": "de"}],
"comments": []
"labels": [{ "value": "New list with IRI", "language": "en"}],
"comments": [{ "value": "New comment", "language": "en"}]
}
```

Expand All @@ -75,13 +94,13 @@ The response will contain the basic information of the list, `listinfo` and an e
"list": {
"children": [],
"listinfo": {
"comments": [],
"comments": [{ "value": "New comment", "language": "en"}],
"id": "http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
"isRootNode": true,
"labels": [
{
"value": "Neue Liste mit IRI",
"language": "de"
"value": "New list with IRI",
"language": "en"
}
],
"name": "a new list",
Expand All @@ -90,18 +109,79 @@ The response will contain the basic information of the list, `listinfo` and an e
}
}
```
### Get list's information

- Required permission: none
- Return list information, `listinfo` (without children).
- GET: `/admin/lists/infos/<listIri>`
### Create new child node

- Required permission: SystemAdmin / ProjectAdmin
- Required fields: `parentNodeIri`, `projectIri`, `labels`,
- 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. If a position is given
for the new child node, the node will be created and inserted in the specified position, otherwise
the node is appended to the end of parent's children.
- POST: `/admin/lists/<parentNodeIri>`
- BODY:

```json
{
"parentNodeIri": "http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
"projectIri": "http://rdfh.ch/projects/0001",
"name": "a child",
"labels": [{ "value": "New List Node", "language": "en"}]
}
```

Additionally, each child node can have an optional custom IRI (of [Knora IRI](../api-v2/knora-iris.md#iris-for-data) form) specified by the `id` in the request body as below:

```json
{ "id": "http://rdfh.ch/lists/0001/8u37MxBVMbX3XQ8-d31x6w",
"parentNodeIri": "http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
"projectIri": "http://rdfh.ch/projects/0001",
"name": "a child",
"labels": [{ "value": "New List Node", "language": "en"}]
}
```

The response will contain the basic information of the node, `nodeinfo`, as below:
```json
{
"nodeinfo": {
"comments": [],
"hasRootNode": "http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
"id": "http://rdfh.ch/lists/0001/8u37MxBVMbX3XQ8-d31x6w",
"labels": [
{
"value": "New List Node",
"language": "en"
}
],
"name": "a new child",
"position": 1
}
}
```
The new node can be created and inserted in a specific position which must be given in the payload as shown below. If necessary,
according to the given position, the sibling nodes will be shifted. Note that `position` cannot have a value higher than the
number of existing children.

```json
{ "parentNodeIri": "http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
"projectIri": "http://rdfh.ch/projects/0001",
"name": "Inserted new child",
"position": 0,
"labels": [{ "value": "New List Node", "language": "en"}]
}
```

In case the new node should be appended to the list of current children, either `position: -1` must be given in the
payload or the `position` parameter must be left out of the payload.

### Update list's information
The basic information of a list such as its labels, comments, name, or all of them can be updated. The parameters that
### Update list's or node's information
The basic information of a list (or node) such as its labels, comments, name, or all of them can be updated. The parameters that
must be updated together with the new value must be given in the JSON body of the request together with the IRI of the
list and the IRI of the project it belongs to.

- Required permission: SystemAdmin / ProjectAdmin
- Required fields: `listIri`, `projectIri`
- Update list information
- PUT: `/admin/lists/<listIri>`
- BODY:
Expand All @@ -115,7 +195,7 @@ list and the IRI of the project it belongs to.
}
```

The response will contain the basic information of the list, `listinfo`, without its children, as below:
The response will contain the basic information of the list, `listinfo` (or `nodeinfo`), without its children, as below:
```json
{
"listinfo": {
Expand Down Expand Up @@ -193,144 +273,6 @@ There is no need to specify the project IRI because it is automatically extracte
```
There is no need to specify the project IRI because it is automatically extracted using the given `<listItemIRI>`.

### Get node

- Required permission: none
- Return complete `node` including basic information of the list, `nodeinfo`, and all its immediate children.
- GET: `/admin/lists/<nodeIri>`

### Get List Node Information

- Required permission: none
- Return node information, `nodeinfo`, (without children).
- GET: `/admin/lists/nodes/<nodeIri>`


### 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. If a position is given
for the new child node, the node will be created and inserted in the specified position, otherwise
the node is appended to the end of parent's children.
- POST: `/admin/lists/<parentNodeIri>`
- BODY:

```json
{
"parentNodeIri": "http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
"projectIri": "http://rdfh.ch/projects/0001",
"name": "a child",
"labels": [{ "value": "New List Node", "language": "en"}],
"comments": []
}
```

Additionally, each child node can have an optional custom IRI (of [Knora IRI](../api-v2/knora-iris.md#iris-for-data) form) specified by the `id` in the request body as below:

```json
{ "id": "http://rdfh.ch/lists/0001/8u37MxBVMbX3XQ8-d31x6w",
"parentNodeIri": "http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
"projectIri": "http://rdfh.ch/projects/0001",
"name": "a child",
"labels": [{ "value": "New List Node", "language": "en"}],
"comments": []
}
```

The response will contain the basic information of the node, `nodeinfo`, as below:
```json
{
"nodeinfo": {
"comments": [],
"hasRootNode": "http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
"id": "http://rdfh.ch/lists/0001/8u37MxBVMbX3XQ8-d31x6w",
"labels": [
{
"value": "New List Node",
"language": "en"
}
],
"name": "a new child",
"position": 1
}
}
```
The new node can be created and inserted in a specific position which must be given in the payload as shown below. If necessary,
according to the given position, the sibling nodes will be shifted. Note that `position` cannot have a value higher than the
number of existing children.

```json
{ "parentNodeIri": "http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
"projectIri": "http://rdfh.ch/projects/0001",
"name": "Inserted new child",
"position": 0,
"labels": [{ "value": "New List Node", "language": "en"}],
"comments": []
}
```

In case the new node should be appended to the list of current children, either `position: -1` must be given in the
payload or the `position` parameter must be left out of the payload.

### Update node's information
The basic information of a node such as its labels, comments, name, or all of them can be updated. The parameters that
must be updated together with the new value must be given in the JSON body of the request together with the IRI of the
node and the IRI of the project it belongs to.

- Required permission: SystemAdmin / ProjectAdmin
- Update node information
- PUT: `/admin/lists/<nodeIri>`
- BODY:

```json
{ "listIri": "http://rdfh.ch/lists/0001/8u37MxBVMbX3XQ8-d31x6w",
"projectIri": "http://rdfh.ch/projects/0001",
"name": "new node name",
"labels": [{ "value": "new node label", "language": "en"}],
"comments": [{ "value": "new node comment", "language": "en"}]
}
```

The response will contain the basic information of the node as `nodeInfo` without its children, as below:

```json
{
"nodeinfo": {
"comments": [
{
"value": "new node comment",
"language": "en"
}
],
"hasRootNode": "http://rdfh.ch/lists/0001/yWQEGXl53Z4C4DYJ-S2c5A",
"id": "http://rdfh.ch/lists/0001/8u37MxBVMbX3XQ8-d31x6w",
"labels": [
{
"value": "new node label",
"language": "en"
}
],
"name": "new node name",
"position": 0
}
}
```

If only name of the node must be updated, it can be given as below in the body of the request:

```json
{
"listIri": "nodeIri",
"projectIri": "projectIri",
"name": "another name"
}
```

Alternatively, basic information of the child node can be updated individually as explained above (See
[update node name](#update-list-or-nodes-name), [update node labels](#update-list-or-nodes-labels), and
[update node comments](#update-list-or-nodes-comments)).

### Repositioning a child node

The position of an existing child node can be updated. The child node can be either repositioned within its
Expand Down

0 comments on commit 24e34dd

Please sign in to comment.