User Groups API Basics
You can Create and Manage User Groups from the Application menu, but you can also use Liferay’s REST APIs. Call these services to manage user groups.
Adding a User Group
Start a new Liferay DXP instance by running
docker run -it -m 8g -p 8080:8080 liferay/dxp:2024.q1.1
Sign in to Liferay at http://localhost:8080 using the email address test@liferay.com and the password test. When prompted, change the password to learn.
Then follow these steps:
-
Download and unzip User Groups API Basics.
curl https://resources.learn.liferay.com/dxp/latest/en/users-and-permissions/developer-guide/liferay-y6f2.zip -O
unzip liferay-y6f2.zip
-
Use the cURL script to add a new user group to your instance. On the command line, navigate to the
curl
folder. Execute theUserGroup_POST_ToInstance.sh
script../UserGroup_POST_ToInstance.sh
The JSON response shows a new user group has been added:
{ "description" : "", "externalReferenceCode" : "72c5739f-a6e9-d4b8-5481-7cf1a427ea79", "id" : 43099, "name" : "Able", "usersCount" : 0 }
-
Navigate to Global Menu → Control Panel → User Groups. See that a new user group has been added.
-
The REST service can also be called using the Java client. Navigate out of the
curl
folder and into thejava
folder. Compile the source files with the following command:javac -classpath .:* *.java
-
Run the
UserGroup_POST_ToInstance.java
class with the following command.java -classpath .:* UserGroup_POST_ToInstance
Examine the cURL Command
The UserGroup_POST_ToInstance.sh
script calls the REST service with a cURL command.
curl \
"http://localhost:8080/o/headless-admin-user/v1.0/user-groups" \
--data-raw '
{
"name": "Able"
}' \
--header "Content-Type: application/json" \
--request "POST" \
--user "test@liferay.com:learn"
Here are the command’s arguments:
Arguments | Description |
---|---|
-H "Content-Type: application/json" | Indicates that the request body format is JSON. |
-X POST | The HTTP method to invoke at the specified endpoint |
"http://localhost:8080/o/headless-admin-user/v1.0/user-groups" | The REST service endpoint |
-d "{\"name\": \"Able\"}" | The data you are requesting to post |
-u "test@liferay.com:learn" | Basic authentication credentials |
Basic authentication is used here for demonstration purposes. For production, you should authorize users via OAuth2. See Using OAuth2 to Authorize Users for a sample React application that uses OAuth2.
The other cURL commands use similar JSON arguments.
Examine the Java Class
The UserGroup_POST_ToInstance.java
class adds a user group by calling the user-group-related service.
public static void main(String[] args) throws Exception {
UserGroupResource.Builder builder = UserGroupResource.builder();
UserGroupResource userGroupResource = builder.authentication(
"test@liferay.com", "learn"
).build();
UserGroup userGroup = userGroupResource.postUserGroup(
new UserGroup() {
{
name = "Dog";
}
});
System.out.println(userGroup);
}
This class invokes the REST service using only three lines of code:
Line (abbreviated) | Description |
---|---|
UserGroupResource.Builder builder = ... | Gets a Builder for generating an UserGroupResource service instance. |
UserGroupResource userGroupResource = builder.authentication(...).build(); | Specifies basic authentication and generates a UserGroupResource service instance. |
UserGroup userGroup = userGroupResource.postUserGroup(...); | Calls the userGroupResource.postUserGroup method and passes the data to post. |
Note that the project includes the com.liferay.headless.admin.user.client.jar
file as a dependency. You can find client JAR dependency information for all REST applications in the API explorer in your installation at /o/api
.
The main
method’s comment demonstrates running the class.
The other example Java classes are similar to this one, but call different UserGroupResource
methods.
See UserGroupResource for service details.
Below are examples of calling other UserGroup
REST services using cURL and Java.
Get User Groups from Instance
You can list User Groups by executing the following cURL or Java command.
UserGroups_GET_FromInstance.sh
Command:
./UserGroups_GET_FromInstance.sh
Code:
curl \
"http://localhost:8080/o/headless-admin-user/v1.0/user-groups" \
--user "test@liferay.com:learn"
UserGroups_GET_FromInstance.java
Command:
java -classpath .:* UserGroups_GET_FromInstance
Code:
UserGroupResource userGroupResource = builder.authentication(
"test@liferay.com", "learn"
).build();
System.out.println(
userGroupResource.getUserGroupsPage(
null, null, Pagination.of(1, 2), null));
}
}
The Instance’s UserGroup
objects appear in JSON.
Get a User Group
Get a specific user group with the following cURL or Java command.
Use UserGroups_GET_FromInstance.[java|sh]
to get instance User Group
IDs.
UserGroup_GET_ById.sh
Command:
./UserGroup_GET_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-admin-user/v1.0/user-groups/${1}" \
--user "test@liferay.com:learn"
UserGroup_GET_ById.java
Command:
java -classpath .:* -DuserGroupId=1234 UserGroup_GET_ById
Code:
public static void main(String[] args) throws Exception {
UserGroupResource.Builder builder = UserGroupResource.builder();
UserGroupResource userGroupResource = builder.authentication(
"test@liferay.com", "learn"
).build();
System.out.println(
userGroupResource.getUserGroup(
Long.valueOf(System.getProperty("userGroupId"))));
}
The UserGroup
fields appear in JSON.
Patch a User Group
Do a partial edit of an existing user group with the following cURL and Java commands. Replace 1234
with your User Group’s ID.
UserGroup_PATCH_ById.sh
Command:
./UserGroup_PATCH_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-admin-user/v1.0/user-groups/${1}" \
--data-raw '
{
"name": "Baker"
}' \
--header "Content-Type: application/json" \
--request "PATCH" \
--user "test@liferay.com:learn"
UserGroup_PATCH_ById.java
Command:
java -classpath .:* -DuserGroupId=1234 UserGroup_PATCH_ById
Code:
public static void main(String[] args) throws Exception {
UserGroupResource.Builder builder = UserGroupResource.builder();
UserGroupResource userGroupResource = builder.authentication(
"test@liferay.com", "learn"
).build();
UserGroup userGroup = userGroupResource.patchUserGroup(
Long.valueOf(System.getProperty("userGroupId")),
new UserGroup() {
{
name = "Easy";
}
});
System.out.println(userGroup);
}
Put a User Group
Completely overwrite an existing user group with the following cURL and Java commands. Replace 1234
with your user group’s ID.
UserGroup_PUT_ById.sh
Command:
./UserGroup_PUT_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-admin-user/v1.0/user-groups/${1}" \
--data-raw '
{
"name": "Charlie"
}' \
--header "Content-Type: application/json" \
--request "PUT" \
--user "test@liferay.com:learn"
UserGroup_PUT_ById.java
Command:
java -classpath .:* -DuserGroupId=1234 UserGroup_PUT_ById
Code:
public static void main(String[] args) throws Exception {
UserGroupResource.Builder builder = UserGroupResource.builder();
UserGroupResource userGroupResource = builder.authentication(
"test@liferay.com", "learn"
).build();
UserGroup userGroup = userGroupResource.putUserGroup(
Long.valueOf(System.getProperty("userGroupId")),
new UserGroup() {
{
name = "Fox";
}
});
System.out.println(userGroup);
}
Delete a User Group
Delete an existing User Group with the following cURL and Java commands. Replace 1234
with your User Group’s ID.
UserGroup_DELETE_ById.sh
Command:
./UserGroup_DELETE_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-admin-user/v1.0/user-groups/${1}" \
--request "DELETE" \
--user "test@liferay.com:learn"
UserGroup_DELETE_ById.java
Command
java -classpath .:* -DuserGroupId=1234 UserGroup_DELETE_ById
Code:
public static void main(String[] args) throws Exception {
UserGroupResource.Builder builder = UserGroupResource.builder();
UserGroupResource userGroupResource = builder.authentication(
"test@liferay.com", "learn"
).build();
userGroupResource.deleteUserGroup(
Long.valueOf(System.getProperty("userGroupId")));
}
The API Explorer shows all of the UserGroup
services and schemas and has an interface to try out each service.