Organizations API Basics
You can Create and Manage Organizations from the Application menu, but you can also use Liferay’s REST APIs. Call these services to manage organizations.
Adding an Organization
Start a new Liferay DXP instance by running
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 Organizations API Basics.
-
Use the cURL script to add a new Organization to your instance. On the command line, navigate to the
curl
folder. Execute theOrganization_POST_ToInstance.sh
script.The JSON response shows a new Organization has been added:
-
Navigate to Global Menu → Control Panel → User and Organizations. Click the Organizations tab. See that a new Organization 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: -
Run the
Organization_POST_ToInstance.java
class with the following command.
Examine the cURL Command
The Organization_POST_ToInstance.sh
script calls the REST service with a cURL command.
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/organizations" | 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 Organization_POST_ToInstance.java
class adds an organization by calling the Organization-related service.
This class invokes the REST service using only three lines of code:
Line (abbreviated) | Description |
---|---|
OrganizationResource.Builder builder = ... | Gets a Builder for generating an OrganizationResource service instance. |
OrganizationResource organizationResource = builder.authentication(...).build(); | Specifies basic authentication and generates a OrganizationResource service instance. |
Organization organization = organizationResource.postOrganization(...); | Calls the organizationResource.postOrganization 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 OrganizationResource
methods.
See OrganizationResource for service details.
Below are examples of calling other Organization
REST services using cURL and Java.
Get Organizations from Instance
You can list Organizations by executing the following cURL or Java command.
Organizations_GET_FromInstance.sh
Command:
Code:
Organizations_GET_FromInstance.java
Command:
Code:
The Instance’s Organization
objects appear in JSON.
Get an Organization
Get a specific Organization with the following cURL or Java command.
Use Organizations_GET_FromInstance.[java|sh]
to get instance Organization
IDs.
Organization_GET_ById.sh
Command:
Code:
Organization_GET_ById.java
Command:
Code:
The Organization
fields appear in JSON.
Patch an Organization
Do a partial edit of an existing Organization with the following cURL and Java commands. Replace 1234
with your Organization’s ID.
Organization_PATCH_ById.sh
Command:
Code:
Organization_PATCH_ById.java
Command:
Code:
Put an Organization
Completely overwrite an existing Organization with the following cURL and Java commands. Replace 1234
with your Organization’s ID.
Organization_PUT_ById.sh
Command:
Code:
Organization_PUT_ById.java
Command:
Code:
Delete an Organization
Delete an existing Organization with the following cURL and Java commands. Replace 1234
with your Organization’s ID.
Organization_DELETE_ById.sh
Command:
Code:
Organization_DELETE_ById.java
Command
Code:
The API Explorer shows all of the Organization
services and schemas and has an interface to try out each service.
Get organization postal addresses with PostalAddresses_GET_FromOrganization