Navigation Menu API Basics
Liferay’s REST APIs provide services for Liferay’s navigation menus. You can create and edit navigation menus with the API. Start by seeing an example of adding a new navigation menu.
Adding a Navigation Menu
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 Categories and Vocabulary API Basics.
curl https://resources.learn.liferay.com/dxp/latest/en/site-building/site-navigation/developer-guide/liferay-p7s4.zip -O
unzip liferay-p7s4.zip
-
Find your site’s ID. You’ll use this in different service calls below.
-
Use the cURL script to add a new navigation menu to your Site. On the command line, navigate to the
curl
folder. Execute theNavigationMenu_POST_ToSite.sh
script with your site ID as a parameter../NavigationMenu_POST_ToSite.sh 1234
The JSON response shows a new navigation menu has been added:
{ "creator" : { "additionalName" : "", "contentType" : "UserAccount", "familyName" : "Test", "givenName" : "Test", "id" : 20129, "name" : "Test Test" }, "dateCreated" : "2021-09-09T21:41:31Z", "dateModified" : "2021-09-09T21:41:31Z", "id" : 40131, "name" : "Foo", "navigationMenuItems" : [ ], "siteId" : 20125 }
-
Go to the Navigation Menus application by navigating to Administration Menu → Site Builder → Navigation Menus. See that a new navigation menu 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
NavigationMenu_POST_ToSite
class with the following command. Replace thesiteId
value with your site’s ID:java -classpath .:* -DsiteId=1234 NavigationMenu_POST_ToSite
Examine the cURL Command
The NavigationMenu_POST_ToSite.sh
script calls the REST service with a cURL command.
curl \
"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/navigation-menus" \
--data-binary '
{
"name": "Foo"
}' \
--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-delivery/v1.0/sites/${1}/navigation-menus" | The REST service endpoint |
-d "{\"name\": \"Foo\"}" | 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 NavigationMenu_POST_ToSite.java
class adds a navigation menu by calling the navigation menu related service.
public static void main(String[] args) throws Exception {
NavigationMenuResource.Builder builder =
NavigationMenuResource.builder();
NavigationMenuResource navigationMenuResource = builder.authentication(
"test@liferay.com", "learn"
).build();
NavigationMenu navigationMenu =
navigationMenuResource.postSiteNavigationMenu(
Long.valueOf(System.getProperty("siteId")),
new NavigationMenu() {
{
name = "Foo";
}
});
System.out.println(navigationMenu);
}
This class invokes the REST service using only three lines of code:
Line (abbreviated) | Description |
---|---|
NavigationMenuResource.Builder builder = ... | Gets a Builder for generating a NavigationMenuResource service instance. |
NavigationMenuResource navigationMenuResource = builder.authentication(...).build(); | Specifies basic authentication and generates a NavigationMenuResource service instance. |
NavigationMenu navigationMenu = navigationMenuResource.postSiteNavigationMenu(...); | Calls the navigationMenuResource.postSiteNavigationMenu method and passes the data to post. |
Note that the project includes the com.liferay.headless.delivery.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 NavigationMenuResource
methods.
See NavigationMenuResource for service details.
Below are examples of calling other NavigationMenu
REST services using cURL and Java.
Get Navigation Menus from Site
You can list a site’s navigation menus by executing the following cURL or Java command. As above, replace 1234
with your site’s ID.
NavigationMenus_GET_FromSite.sh
Command:
./NavigationMenus_GET_FromSite.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/navigation-menus" \
--user "test@liferay.com:learn"
NavigationMenus_GET_FromSite.java
Command:
java -classpath .:* -DsiteId=1234 NavigationMenus_GET_FromSite
Code:
public static void main(String[] args) throws Exception {
NavigationMenuResource.Builder builder =
NavigationMenuResource.builder();
NavigationMenuResource navigationMenuResource = builder.authentication(
"test@liferay.com", "learn"
).build();
Page<NavigationMenu> page =
navigationMenuResource.getSiteNavigationMenusPage(
Long.valueOf(System.getProperty("siteId")),
Pagination.of(1, 2));
System.out.println(page);
}
The site’s NavigationMenu
objects are listed in JSON.
Get a Navigation Menu
Get a specific navigation menu with the following cURL or Java command. Replace 1234
with the navigation menu’s ID.
Use NavigationMenus_GET_FromSite.[java|sh]
to get NavigationMenu
IDs.
NavigationMenu_GET_ById.sh
Command:
./NavigationMenu_GET_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-delivery/v1.0/navigation-menus/${1}" \
--user "test@liferay.com:learn"
NavigationMenu_GET_ById.java
Command:
java -classpath .:* -DnavigationMenuId=1234 NavigationMenu_GET_ById
Code:
public static void main(String[] args) throws Exception {
NavigationMenuResource.Builder builder =
NavigationMenuResource.builder();
NavigationMenuResource navigationMenuResource = builder.authentication(
"test@liferay.com", "learn"
).build();
System.out.println(
navigationMenuResource.getNavigationMenu(
Long.valueOf(System.getProperty("navigationMenuId"))));
}
The NavigationMenu
fields are listed in JSON.
Put a Navigation Menu
Do a complete overwrite of an existing navigation menu with the following cURL and Java commands. Note, replace 1234
with your navigation menu’s ID.
NavigationMenu_PUT_ById.sh
Command:
./NavigationMenu_PUT_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-delivery/v1.0/navigation-menus/${1}" \
--data-binary '
{
"name": "Bar"
}' \
--header "Content-Type: application/json" \
--request "PUT" \
--user "test@liferay.com:learn"
NavigationMenu_PUT_ById.java
Command:
java -classpath .:* -DnavigationMenuId=1234 NavigationMenu_PUT_ById
Code:
public static void main(String[] args) throws Exception {
NavigationMenuResource.Builder builder =
NavigationMenuResource.builder();
NavigationMenuResource navigationMenuResource = builder.authentication(
"test@liferay.com", "learn"
).build();
NavigationMenu navigationMenu =
navigationMenuResource.putNavigationMenu(
Long.valueOf(System.getProperty("navigationMenuId")),
new NavigationMenu() {
{
name = "Bar";
}
});
System.out.println(navigationMenu);
}
Delete a Navigation Menu
Delete an existing navigation menu with the following cURL and Java commands. Note, replace 1234
with your navigation menu’s ID.
NavigationMenu_DELETE_ById.sh
Command:
./NavigationMenu_DELETE_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-delivery/v1.0/navigation-menus/${1}" \
--request "DELETE" \
--user "test@liferay.com:learn"
NavigationMenu_DELETE_ById.java
Command
java -classpath .:* -DnavigationMenuId=1234 NavigationMenu_DELETE_ById
Code:
public static void main(String[] args) throws Exception {
NavigationMenuResource.Builder builder =
NavigationMenuResource.builder();
NavigationMenuResource navigationMenuResource = builder.authentication(
"test@liferay.com", "learn"
).build();
navigationMenuResource.deleteNavigationMenu(
Long.valueOf(System.getProperty("navigationMenuId")));
}
The API Explorer lists all of the NavigationMenu
services and schemas and has an interface to try out each service.