Warehouse API Basics
You can manage warehouses from the Applications menu or REST APIs. Call the headless-commerce-admin-inventory services to create and manage warehouses.
Adding a Warehouse
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.
Once Liferay is running,
-
Download and unzip Warehouse API Basics.
curl https://resources.learn.liferay.com/commerce/latest/en/inventory-management/developer-guide/liferay-v9s5.zip -O
unzip liferay-v9s5.zip
-
Warehouses are scoped to an instance. Use the cURL script to add a new warehouse. On the command line, navigate to the
curl
folder. Execute theWarehouse_POST_ToInstance.sh
script../Warehouse_POST_ToInstance.sh
The JSON response shows a new warehouse was added:
{ "actions" : { "permissions" : { "method" : "PATCH", "href" : "http://localhost:8080/o/headless-commerce-admin-inventory/v1.0/warehouses/46429" }, "get" : { "method" : "GET", "href" : "http://localhost:8080/o/headless-commerce-admin-inventory/v1.0/warehouses" }, "update" : { "method" : "PATCH", "href" : "http://localhost:8080/o/headless-commerce-admin-inventory/v1.0/warehouses/46429" }, "delete" : { "method" : "DELETE", "href" : "http://localhost:8080/o/headless-commerce-admin-inventory/v1.0/warehouses/46429" } }, "active" : false, "city" : "", "countryISOCode" : "", "description" : { }, "externalReferenceCode" : "c441eb70-dcd4-e040-92e5-eae0727cc958", "id" : 46429, "latitude" : 0.0, "longitude" : 0.0, "name" : { "en_US" : "Foo" }, "regionISOCode" : "", "street1" : "", "street2" : "", "street3" : "", "type" : "", "zip" : "" }
-
To verify the warehouse addition, open the Global Menu () and navigate to Commerce → Warehouses. The new warehouse appears.
noteThe new warehouse is inactive. Set its
latitude
andlongitude
coordinates before activating it. -
Alternatively, call the REST service using the Java client. Navigate into the
java
folder and compile the source files:javac -classpath .:* *.java
-
Run the
Warehouse_POST_ToInstance
class.java -classpath .:* Warehouse_POST_ToInstance
Examine the cURL Command
The Warehouse_POST_ToInstance.sh
script calls the REST service with a cURL command.
curl \
"http://localhost:8080/o/headless-commerce-admin-inventory/v1.0/warehouses" \
--data-raw '
{
"active": false,
"name": {
"en_US": "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" | Set the request body format to JSON. |
-X POST | Set the HTTP method to invoke at the specified endpoint. |
"http://localhost:8080/o/headless-commerce-admin-inventory/v1.0/warehouses" | Specify the REST service endpoint. |
-d "{\"active\": false, \"name\": {\"en_US\": \"Foo\"}}" | Enter the data to post. |
-u "test@liferay.com:learn" | Enter 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 using OAuth2.
The other cURL commands use similar JSON arguments.
Examine the Java Class
The Warehouse_POST_ToInstance.java
class adds a warehouse by calling the WarehouseResource
service.
public static void main(String[] args) throws Exception {
WarehouseResource.Builder builder = WarehouseResource.builder();
WarehouseResource warehouseResource = builder.authentication(
"test@liferay.com", "learn"
).build();
System.out.println(
warehouseResource.postWarehouse(
new Warehouse() {
{
active = false;
name = new HashMap<String, String>() {
{
put("en_US", "Foo");
}
};
}
}));
}
This class invokes the REST service using only three lines of code:
Line (abbreviated) | Description |
---|---|
WarehouseResource.Builder builder = ... | Get a Builder for generating a WarehouseResource service instance. |
WarehouseResource warehouseResource = builder.authentication(...).build(); | Use basic authentication and generate a WarehouseResource service instance. |
warehouseResource.postWarehouse(...); | Call the warehouseResource.postWarehouse method and pass the data to post. |
The project includes the com.liferay.headless.commerce.admin.inventory.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
(e.g., http://localhost:8080/o/api).
The main
method’s comment demonstrates running the class.
The remaining example Java classes call different WarehouseResource
methods.
See WarehouseResource for service details.
Below are examples of calling other Warehouse
REST services using cURL and Java.
Get Warehouses from Instance
List all the warehouses in your Liferay instance with a cURL or Java command.
Warehouses_GET_FromInstance.sh
Command:
./Warehouses_GET_FromInstance.sh
Code:
curl \
"http://localhost:8080/o/headless-commerce-admin-inventory/v1.0/warehouses" \
--user "test@liferay.com:learn"
Warehouses_GET_FromInstance.java
Command:
java -classpath .:* Warehouses_GET_FromInstance
Code:
WarehouseResource warehouseResource = builder.authentication(
"test@liferay.com", "learn"
).build();
System.out.println(
warehouseResource.getWarehousesPage(
null, Pagination.of(1, 2), null));
}
}
The instance’s Warehouse
objects are formatted in JSON.
Filtering, Paginating, and Sorting Warehouses
This API also accepts parameters to filter, paginate, and sort the warehouses. See the getWarehousesPage
method for more information. You can use the following Warehouse
fields in your queries to filter and sort the results.
- active
- city
- countryISOCode
- latitude
- longitude
- name
- regionISOCode
- street1
Filter Query | Description |
---|---|
active eq true | The warehouse must be active. |
name eq 'Foo' | The warehouse name must equal ‘Foo’ |
latitude eq 12.0 | The warehouse latitude must equal 12.0 |
Sort Query | Description |
---|---|
name:desc | Sort by name in descending order |
countryISOCode:desc | Sort by country ISO code in descending order |
Read API Query Parameters for more information.
Get a Warehouse
Get a specific warehouse with cURL or Java get
commands. Replace 1234
with the warehouse’s ID.
Use Warehouses_GET_FromInstance.[java|sh]
to get a list of all warehouses and note the id
of the warehouse you want specifically.
Warehouse_GET_ById.sh
Command:
./Warehouse_GET_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-commerce-admin-inventory/v1.0/warehouses/${1}" \
--user "test@liferay.com:learn"
Warehouse_GET_ById.java
Command:
java -classpath .:* -DwarehouseId=1234 Warehouse_GET_ById
Code:
public static void main(String[] args) throws Exception {
WarehouseResource.Builder builder = WarehouseResource.builder();
WarehouseResource warehouseResource = builder.authentication(
"test@liferay.com", "learn"
).build();
System.out.println(
warehouseResource.getWarehouseId(
Long.valueOf(System.getProperty("warehouseId"))));
}
The Warehouse
fields are listed in JSON.
Patch a Warehouse
Update an existing warehouse with cURL and Java patch
commands. Replace 1234
with your warehouse’s ID.
Warehouse_PATCH_ById.sh
Command:
./Warehouse_PATCH_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-commerce-admin-inventory/v1.0/warehouses/${1}" \
--data-raw '
{
"name": {
"en_US": "Bar"
}
}' \
--header "Content-Type: application/json" \
--request "PATCH" \
--user "test@liferay.com:learn"
Warehouse_PATCH_ById.java
Command:
java -classpath .:* -DwarehouseId=1234 Warehouse_PATCH_ById
Code:
public static void main(String[] args) throws Exception {
WarehouseResource.Builder builder = WarehouseResource.builder();
WarehouseResource warehouseResource = builder.authentication(
"test@liferay.com", "learn"
).build();
warehouseResource.patchWarehouseId(
Long.valueOf(System.getProperty("warehouseId")),
new Warehouse() {
{
name = new HashMap<String, String>() {
{
put("en_US", "Bar");
}
};
}
});
}
Delete a Warehouse
Delete an existing warehouse with cURL and Java delete
commands. Replace 1234
with your warehouse’s ID.
Warehouse_DELETE_ById.sh
Command:
./Warehouse_DELETE_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-commerce-admin-inventory/v1.0/warehouses/${1}" \
--request "DELETE" \
--user "test@liferay.com:learn"
Warehouse_DELETE_ById.java
Command
java -classpath .:* -DwarehouseId=1234 Warehouse_DELETE_ById
Code:
public static void main(String[] args) throws Exception {
WarehouseResource.Builder builder = WarehouseResource.builder();
WarehouseResource warehouseResource = builder.authentication(
"test@liferay.com", "learn"
).build();
warehouseResource.deleteWarehouseId(
Long.valueOf(System.getProperty("warehouseId")));
}
The API Explorer shows the Warehouse
services and schemas and has an interface to test each service.