Navigation Menu API Basics - Liferay Official Documentation

Submit Feedback

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.

Note

Liferay DXP 2025.Q2+/Portal GA135+ The Navigation Menus API now uses External Reference Codes (ERCs) to reference these elements, enabling consistent identification across instances and supporting batch export/import for improved content management and portability.

Start a new Liferay DXP instance by running

docker run -it -m 8g -p 8080:8080 liferay/dxp:2025.q1.6-lts

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/examples/liferay-p7s4.zip -O

unzip liferay-p7s4.zip

Find your site ID. Use it 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 the NavigationMenus_POST_ToSites.sh script with your site ID as a parameter.

./NavigationMenus_POST_ToSites.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 the java folder. Compile the source files with the following command:
```
javac -classpath .:* *.java
```
Run the NavigationMenus_POST_ToSites class with the following command. Replace the siteId value with your site ID:
```
java -classpath .:* -DsiteId=1234 NavigationMenus_POST_ToSites
```

Examine the cURL Command

The NavigationMenus_POST_ToSites.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

Note

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 NavigationMenus_POST_ToSites.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.

Note

The main method’s comment demonstrates running the class.

The other example Java classes are similar to this one, but call different NavigationMenuResource methods.

Important

See NavigationMenuResource for service details.

Below are examples of calling other NavigationMenu REST services using cURL and Java.

You can list a site’s navigation menus by executing the following cURL or Java command. As above, replace 1234 with your site ID.

NavigationMenus_GET_FromSites.sh

Command:

./NavigationMenus_GET_FromSites.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/navigation-menus" \
	--user "test@liferay.com:learn"

NavigationMenus_GET_FromSites.java

Command:

java -classpath .:* -DsiteId=1234 NavigationMenus_GET_FromSites

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 appear in JSON.

Get a specific navigation menu with the following cURL or Java command. Replace 1234 with the navigation menu’s ID.

Tip

Use NavigationMenus_GET_FromSites.[java|sh] to get NavigationMenu IDs.

NavigationMenus_GET_ById.sh

Command:

./NavigationMenus_GET_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/navigation-menus/${1}" \
	--user "test@liferay.com:learn"

NavigationMenus_GET_ById.java

Command:

java -classpath .:* -DnavigationMenuId=1234 NavigationMenus_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 appear in JSON.

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.

NavigationMenus_PUT_ById.sh

Command:

./NavigationMenus_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"

NavigationMenus_PUT_ById.java

Command:

java -classpath .:* -DnavigationMenuId=1234 NavigationMenus_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 an existing navigation menu with the following cURL and Java commands. Note, replace 1234 with your navigation menu’s ID.

NavigationMenus_DELETE_ById.sh

Command:

./NavigationMenus_DELETE_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/navigation-menus/${1}" \
	--request "DELETE" \
	--user "test@liferay.com:learn"

NavigationMenus_DELETE_ById.java

Command

java -classpath .:* -DnavigationMenuId=1234 NavigationMenus_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")));
}