Skip to content

REST API ref: Merge /user/groups/{id}/ into /user/groups/{path}/ #1843

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
adriendupuis merged 4 commits into from
Jan 9, 2023
Merged

REST API ref: Merge /user/groups/{id}/ into /user/groups/{path}/ #1843

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
9b1897c
ez-user-groups.raml: Merge /{id}/users into /{path}/users
adriendupuis Dec 28, 2022
73d4ac6
ez-user-groups.raml: Merge /{id}/subgroups into /{path}/subgroups
adriendupuis Dec 28, 2022
72aaa84
Regenerate rest_api_reference.html
adriendupuis Jan 5, 2023
2d60b78
Regenerate rest_api_reference.html
adriendupuis Jan 9, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
122 changes: 60 additions & 62 deletions docs/api/rest_api/rest_api_reference/input/ez-user-groups.raml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,36 @@ get:
404:
description: Error - the User Group does not exist.
/users:
get:
displayName: Load Users of Group
description: Loads the Users of the Group with the given ID.
Copy link
Contributor Author

@adriendupuis adriendupuis Dec 29, 2022 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The controller is extracting the ID from the path argument by splitting this path on slashes and keeping the last item ( extractLocationIdFromPath). So, it works with just the ID.

The description is not wrong but doesn't cover the whole possibilities. If having only a path, a developer shouldn't extract the ID from this path before use but directly use this path. Anyway, just having access to the path seems like a rare case to me, and an ID simpler to use.

This is a more general problem than just below /user/groups/{path}/;
Other routes having a {path} argument are in fact extracting the ID from it with their documentation not saying it.
From my PoV, the worst could be /content/locations/{path} description only documenting the path while its controller will extract the ID from this path. The 3 following example are equivalent but only the complex one is proposed:

  • /content/locations/1/2/61 (full path)
  • /content/locations/2/61 (incomplete path)
  • /content/locations/61 (ID)

I propose to not edit this description in this PR.

queryParameters:
limit:
description: Only 'limit' items will be returned started by offset.
offset:
description: Offset of the result set.
headers:
Accept:
description: UserList - If set, the User list returned in XML or JSON format. UserRefList - If set, the link list of Users returned in XML or JSON format.
example: |
application/vnd.ibexa.api.UserList+xml
application/vnd.ibexa.api.UserList+json
application/vnd.ibexa.api.UserRefList+xml
application/vnd.ibexa.api.UserRefList+json
responses:
200:
description: OK - the Users of the Group with the given ID.
body:
application/vnd.ibexa.api.UserRefList+xml:
type: UserRefList
example: !include examples/user/groups/id/users/GET/UserRefList.xml.example
application/vnd.ibexa.api.UserRefList+json:
type: UserRefList
example: !include examples/user/groups/id/users/GET/UserRefList.json.example
401:
description: Error - the user has no permission to read User Groups.
404:
description: Error - the User Group does not exist.
post:
displayName: Create User
description: Creates a new User in the given Group.
Expand Down Expand Up @@ -166,6 +196,36 @@ get:
404:
description: Error - the Group with the given ID does not exist.
/subgroups:
get:
displayName: Load subgroups
description: Returns a list of the subgroups.
queryParameters:
limit:
description: The number of Locations returned.
offset:
description: The offset of the result set.
headers:
Accept:
description: UserGroupList - If set, the User Group list is returned in XML or JSON format. UserGroupRefList - If set, the link list of User Groups is returned in XML or JSON format.
example: |
application/vnd.ibexa.api.UserGroupList+xml
application/vnd.ibexa.api.UserGroupList+json
application/vnd.ibexa.api.UserGroupRefList+xml
application/vnd.ibexa.api.UserGroupRefList+json
responses:
200:
description: OK - list of the subgroups.
body:
application/vnd.ibexa.api.UserGroupRefList+xml:
type: UserGroupRefList
example: !include examples/user/groups/id/subgroups/GET/UserGroupRefList.xml.example
application/vnd.ibexa.api.UserGroupRefList+json:
type: UserGroupRefList
example: !include examples/user/groups/id/subgroups/GET/UserGroupRefList.json.example
401:
description: Error - the user has no permission to read User Groups.
404:
description: Error - the User Group does not exist.
post:
displayName: Create User Group
description: Creates a new User Group under the given parent. To create a top level group use '/user/groups/subgroups'.
Expand Down Expand Up @@ -298,65 +358,3 @@ get:
example: !include examples/user/groups/path/roles/role_id/DELETE/RoleAssignmentList.json.example
401:
description: Error - the user is not authorized to delete this Role assignment.
/{id}/users:
get:
displayName: Load Users of Group
description: Loads the Users of the Group with the given ID.
queryParameters:
limit:
description: Only 'limit' items will be returned started by offset.
offset:
description: Offset of the result set.
headers:
Accept:
description: UserList - If set, the User list returned in XML or JSON format. UserRefList - If set, the link list of Users returned in XML or JSON format.
example: |
application/vnd.ibexa.api.UserList+xml
application/vnd.ibexa.api.UserList+json
application/vnd.ibexa.api.UserRefList+xml
application/vnd.ibexa.api.UserRefList+json
responses:
200:
description: OK - the Users of the Group with the given ID.
body:
application/vnd.ibexa.api.UserRefList+xml:
type: UserRefList
example: !include examples/user/groups/id/users/GET/UserRefList.xml.example
application/vnd.ibexa.api.UserRefList+json:
type: UserRefList
example: !include examples/user/groups/id/users/GET/UserRefList.json.example
401:
description: Error - the user has no permission to read User Groups.
404:
description: Error - the User Group does not exist.
/{id}/subgroups:
get:
displayName: Load subgroups
description: Returns a list of the subgroups.
queryParameters:
limit:
description: The number of Locations returned.
offset:
description: The offset of the result set.
headers:
Accept:
description: UserGroupList - If set, the User Group list is returned in XML or JSON format. UserGroupRefList - If set, the link list of User Groups is returned in XML or JSON format.
example: |
application/vnd.ibexa.api.UserGroupList+xml
application/vnd.ibexa.api.UserGroupList+json
application/vnd.ibexa.api.UserGroupRefList+xml
application/vnd.ibexa.api.UserGroupRefList+json
responses:
200:
description: OK - list of the subgroups.
body:
application/vnd.ibexa.api.UserGroupRefList+xml:
type: UserGroupRefList
example: !include examples/user/groups/id/subgroups/GET/UserGroupRefList.xml.example
application/vnd.ibexa.api.UserGroupRefList+json:
type: UserGroupRefList
example: !include examples/user/groups/id/subgroups/GET/UserGroupRefList.json.example
401:
description: Error - the user has no permission to read User Groups.
404:
description: Error - the User Group does not exist.
Loading