Countries API Basics¶
Available Liferay 7.4 U24+ and GA24+
Use Liferay’s Rest APIs to create and manage countries.
Adding a Country¶
Start a new Liferay DXP instance by running
docker run -it -m 8g -p 8080:8080 liferay/dxp:7.4.13-u29
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 Countries API Basics.
curl https://learn.liferay.com/dxp/latest/en/users-and-permissions/developer-guide/liferay-g6m8.zip -O
unzip liferay-g6m8.zip
Use the cURL script to add a new country to your instance. On the command line, navigate to the
curl
folder. Execute theCountry_POST_ToInstance.sh
script../Country_POST_ToInstance.sh
The JSON response shows a new country has been added:
"a2" : "AB", "a3" : "ABL", "active" : true, "billingAllowed" : true, "groupFilterEnabled" : false, "id" : 43501, "name" : "Foo", "number" : 1234, "position" : 0.0, "regions" : [ ], "shippingAllowed" : true, "subjectToVAT" : false, "title_i18n" : { }, "zipRequired" : true
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 like this:javac -classpath .:* *.java
Run the
Country_POST_ToInstance.java
class:java -classpath .:* Country_POST_ToInstance
Examine the cURL Command¶
The Country_POST_ToInstance.sh
script calls the REST service with a cURL command.
Here are the command’s arguments:
Arguments |
Description |
---|---|
|
Indicates that the request body format is JSON. |
|
The HTTP method to invoke at the specified endpoint |
|
The REST service endpoint |
|
The data you are requesting to post |
|
Basic authentication credentials |
Note
Basic authentication is used here for demonstration purposes. For production, you should authorize users via OAuth2.
The other cURL commands use similar JSON arguments.
Examine the Java Class¶
The Country_POST_ToInstance.java
class adds a country by calling the Country-related service.
public static void main(String[] args) throws Exception {
CountryResource.Builder builder = CountryResource.builder();
CountryResource countryResource = builder.authentication(
"[email protected]", "learn"
).build();
Country country = countryResource.postCountry(
new Country() {
{
a2 = "AB";
a3 = "ABL";
name = "Foo";
number = 1234;
}
});
System.out.println(country);
}
This class invokes the REST service using only three lines of code:
Line (abbreviated) |
Description |
---|---|
|
Gets a |
|
Specifies basic authentication and generates a |
|
Calls the |
Note that the project includes the com.liferay.headless.admin.address.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 CountryResource
methods.
Important
See CountryResource for service details.
Below are examples of calling other Country
REST services using cURL and Java.
Get Countries from Instance¶
You can list countries by executing the following cURL or Java command.
Countries_GET_FromInstance.sh¶
Command:
./Countries_GET_FromInstance.sh
Code:
curl \
"http://localhost:8080/o/headless-admin-address/v1.0/countries" \
-u "[email protected]:learn"
Countries_GET_FromInstance.java¶
Command:
java -classpath .:* Countries_GET_FromInstance
Code:
public static void main(String[] args) throws Exception {
CountryResource.Builder builder = CountryResource.builder();
CountryResource countryResource = builder.authentication(
"[email protected]", "learn"
).build();
Page<Country> page = countryResource.getCountriesPage(
null, null, Pagination.of(1, 2), null);
System.out.println(page);
}
The Instance’s Country
objects appear in JSON.
Get a Country¶
Get a specific country with the following cURL or Java command.
Tip
Use Countries_GET_FromInstance.[java|sh]
to get instance Country
IDs.
Country_GET_ById.sh¶
Command:
./Country_GET_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-admin-address/v1.0/countries/${1}" \
-u "[email protected]:learn"
Country_GET_ById.java¶
Command:
java -classpath .:* -DcountryId=1234 Country_GET_ById
Code:
public static void main(String[] args) throws Exception {
CountryResource.Builder builder = CountryResource.builder();
CountryResource countryResource = builder.authentication(
"[email protected]", "learn"
).build();
Country country = countryResource.getCountry(
Long.valueOf(System.getProperty("countryId")));
System.out.println(country);
}
The Country
fields appear in JSON.
Patch a Country¶
Do a partial edit of an existing country with the following cURL and Java commands. Replace 1234
with your country’s ID.
Country_PATCH_ById.sh¶
Command:
./Country_PATCH_ById.sh 1234
Code:
curl \
-H "Content-Type: application/json" \
-X PATCH \
"http://localhost:8080/o/headless-admin-address/v1.0/countries/${1}" \
-d "{\"name\": \"Bar\"}" \
-u "[email protected]:learn"
Country_PATCH_ById.java¶
Command:
java -classpath .:* -DcountryId=1234 Country_PATCH_ById
Code:
public static void main(String[] args) throws Exception {
CountryResource.Builder builder = CountryResource.builder();
CountryResource countryResource = builder.authentication(
"[email protected]", "learn"
).build();
Country country = countryResource.patchCountry(
Long.valueOf(System.getProperty("countryId")),
new Country() {
{
name = "Bar";
}
});
System.out.println(country);
}
Put a Country¶
Completely overwrite an existing country with the following cURL and Java commands. Replace 1234
with your country’s ID.
Country_PUT_ById.sh¶
Command:
./Country_PUT_ById.sh 1234
Code:
curl \
-H "Content-Type: application/json" \
-X PUT \
"http://localhost:8080/o/headless-admin-address/v1.0/countries/${1}" \
-d "{\"a2\": \"AB\", \"a3\": \"ABL\", \"name\": \"Goo\", \"number\": \"1234\"}" \
-u "[email protected]:learn"
Country_PUT_ById.java¶
Command:
java -classpath .:* -DcountryId=1234 Country_PUT_ById
Code:
public static void main(String[] args) throws Exception {
CountryResource.Builder builder = CountryResource.builder();
CountryResource countryResource = builder.authentication(
"[email protected]", "learn"
).build();
Country country = countryResource.putCountry(
Long.valueOf(System.getProperty("countryId")),
new Country() {
{
a2 = "AB";
a3 = "ABL";
name = "Goo";
number = 1234;
}
});
System.out.println(country);
}
Delete a Country¶
Delete an existing country with the following cURL and Java commands. Replace 1234
with your country’s ID.
Country_DELETE_ById.sh¶
Command:
./Country_DELETE_ById.sh 1234
Code:
curl \
-X DELETE \
"http://localhost:8080/o/headless-admin-address/v1.0/countries/${1}" \
-u "[email protected]:learn"
Country_DELETE_ById.java¶
Command
java -classpath .:* -DcountryId=1234 Country_DELETE_ById
Code:
public static void main(String[] args) throws Exception {
CountryResource.Builder builder = CountryResource.builder();
CountryResource countryResource = builder.authentication(
"[email protected]", "learn"
).build();
countryResource.deleteCountry(
Long.valueOf(System.getProperty("countryId")));
}
The API Explorer shows all of the Country
services and schemas and has an interface to try out each service.