Knowledge Base API Basics
You can Create Knowledge Base Articles and Manage the Knowledge Base with Liferay’s Knowledge Base app, but you can also use Liferay’s REST APIs. Call these services to create and manage content for your Knowledge Base.
Adding a Knowledge Base Article
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 Knowledge Base API Basics.
curl https://resources.learn.liferay.com/dxp/latest/en/collaboration-and-social/knowledge-base/developer-guide/liferay-t3x7.zip -O
unzip liferay-t3x7.zip
-
When signed in, retrieve the site’s ID. You’ll use this ID in several service calls.
-
Use the cURL script to add a new Knowledge Base article to your site. On the command line, navigate to the
curl
folder. Execute theKnowledgeBaseArticle_POST_ToSite.sh
script with your site ID as a parameter. For example,./KnowledgeBaseArticle_POST_ToSite.sh 1234
The JSON response shows a new Knowledge Base article has been added:
{ "articleBody" : "Foo", "creator" : { "additionalName" : "", "contentType" : "UserAccount", "familyName" : "Test", "givenName" : "Test", "id" : 20125, "name" : "Test Test" }, "customFields" : [ ], "dateCreated" : "2022-07-28T21:25:57Z", "dateModified" : "2022-07-28T21:25:57Z", "description" : "", "encodingFormat" : "text/html", "externalReferenceCode" : "0bace9ad-39ea-79b5-902e-c873806b8bd7", "friendlyUrlPath" : "able", "id" : 42447, "keywords" : [ ], "numberOfAttachments" : 0, "numberOfKnowledgeBaseArticles" : 0, "parentKnowledgeBaseArticleId" : 0, "relatedContents" : [ ], "siteId" : 20121, "subscribed" : false, "taxonomyCategoryBriefs" : [ ], "title" : "Able" }
-
Click the Menu icon () and navigate to Content and Data → Knowledge Base. See that a new Knowledge Base article 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:javac -classpath .:* *.java
-
Run the
KnowledgeBaseArticle_POST_ToSite.java
class. Replace thesiteId
system property value with your site’s ID.java -classpath .:* -DsiteId=1234 KnowledgeBaseArticle_POST_ToSite
The Java class created a new Knowledge Base article.
Examine the cURL Command
The KnowledgeBaseArticle_POST_ToSite.sh
script calls the REST service with a cURL command.
curl \
"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/knowledge-base-articles" \
--data-raw '
{
"articleBody": "Foo",
"title": "Able"
}' \
--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}/knowledge-base-articles" | The REST service endpoint |
-d "{\"articleBody\": \"Foo\", \"title\": \"Able\"}" | The data you are requesting to post |
-u "test@liferay.com:learn" | Basic authentication credentials |
Basic authentication is used 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 KnowledgeBaseArticle_POST_ToSite.java
class adds a Knowledge Base article by calling the knowledge-base-related service.
public static void main(String[] args) throws Exception {
KnowledgeBaseArticleResource.Builder builder =
KnowledgeBaseArticleResource.builder();
KnowledgeBaseArticleResource knowledgeBaseArticleResource =
builder.authentication(
"test@liferay.com", "learn"
).build();
KnowledgeBaseArticle knowledgeBaseArticle =
knowledgeBaseArticleResource.postSiteKnowledgeBaseArticle(
Long.valueOf(System.getProperty("siteId")),
new KnowledgeBaseArticle() {
{
articleBody = "Foo";
title = "Charlie";
}
});
System.out.println(knowledgeBaseArticle);
}
This class invokes the REST service using only three lines of code:
Line (abbreviated) | Description |
---|---|
KnowledgeBaseArticleResource.Builder builder = ... | Gets a Builder for generating an KnowledgeBaseArticleResource service instance. |
KnowledgeBaseArticleGroupResource knowledgeBaseArticleGroupResource = builder.authentication(...).build(); | Specifies basic authentication and generates a KnowledgeBaseArticleResource service instance. |
KnowledgeBaseArticle knowledgeBaseArticle = knowledgeBaseArticleResource.postSiteKnowledgeBaseArticle(...); | Calls the knowledgeBaseArticleResource.postSiteKnowledgeBaseArticle 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 KnowledgeBaseArticle
methods.
See KnowledgeBaseArticleResource for service details.
Below are examples of calling other KnowledgeBaseArticle
REST services using cURL and Java.
Get Knowledge Base Articles from Site
You can retrieve Knowledge Base articles from any site by executing the following cURL or Java command. Replace 1234
with your site’s ID.
KnowledgeBaseArticles_GET_FromSite.sh
Command:
./KnowledgeBaseArticles_GET_FromSite.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/knowledge-base-articles" \
--user "test@liferay.com:learn"
KnowledgeBaseArticles_GET_FromSite.java
Command:
java -classpath .:* -DsiteId=1234 KnowledgeBaseArticles_GET_FromSite
Code:
public static void main(String[] args) throws Exception {
KnowledgeBaseArticleResource.Builder builder =
KnowledgeBaseArticleResource.builder();
KnowledgeBaseArticleResource knowledgeBaseArticleResource =
builder.authentication(
"test@liferay.com", "learn"
).build();
Page<KnowledgeBaseArticle> page =
knowledgeBaseArticleResource.getSiteKnowledgeBaseArticlesPage(
Long.valueOf(System.getProperty("siteId")), null, null, null,
null, Pagination.of(1, 2), null);
System.out.println(page);
}
The Instance’s KnowledgeBaseArticles
objects appear in JSON.
Get a Knowledge Base Article
Get a specific Knowledge Base article by its ID with the following cURL or Java command.
Use KnowledgeBaseArticles_GET_FromSite.[java|sh]
to get instance Knowledge Base Article
IDs.
KnowledgeBaseArticle_GET_ById.sh
Command:
./KnowledgeBaseArticle_GET_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-delivery/v1.0/knowledge-base-articles/${1}" \
--user "test@liferay.com:learn"
KnowledgeBaseArticle_GET_ById.java
Command:
java -classpath .:* -DknowledgeBaseArticleId=1234 KnowledgeBaseArticle_GET_ById
Code:
public static void main(String[] args) throws Exception {
KnowledgeBaseArticleResource.Builder builder =
KnowledgeBaseArticleResource.builder();
KnowledgeBaseArticleResource knowledgeBaseArticleResource =
builder.authentication(
"test@liferay.com", "learn"
).build();
System.out.println(
knowledgeBaseArticleResource.getKnowledgeBaseArticle(
Long.valueOf(System.getProperty("knowledgeBaseArticleId"))));
}
The KnowledgeBaseArticle
fields appear in JSON.
Patch a Knowledge Base Article
Do a partial edit of an existing Knowledge Base article with the following cURL and Java commands. Replace 1234
with your Knowledge Base article’s ID. Specify the field you want to modify and its new value.
KnowledgeBaseArticle_PATCH_ById.sh
Command:
./KnowledgeBaseArticle_PATCH_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-delivery/v1.0/knowledge-base-articles/${1}" \
--data-raw '
{
"articleBody": "Bar"
}' \
--header "Content-Type: application/json" \
--request "PATCH" \
--user "test@liferay.com:learn"
KnowledgeBaseArticle_PATCH_ById.java
Command:
java -classpath .:* -DknowledgeBaseArticleId=1234 KnowledgeBaseArticle_PATCH_ById
Code:
public static void main(String[] args) throws Exception {
KnowledgeBaseArticleResource.Builder builder =
KnowledgeBaseArticleResource.builder();
KnowledgeBaseArticleResource knowledgeBaseArticleResource =
builder.authentication(
"test@liferay.com", "learn"
).build();
KnowledgeBaseArticle knowledgeBaseArticle =
knowledgeBaseArticleResource.patchKnowledgeBaseArticle(
Long.valueOf(System.getProperty("knowledgeBaseArticleId")),
new KnowledgeBaseArticle() {
{
articleBody = "Bar";
}
});
System.out.println(knowledgeBaseArticle);
}
Put a Knowledge Base Article
Completely overwrite an existing Knowledge Base article with the following cURL and Java commands. Replace 1234
with your Knowledge Base article’s ID.
KnowledgeBaseArticle_PUT_ById.sh
Command:
./KnowledgeBaseArticle_PUT_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-delivery/v1.0/knowledge-base-articles/${1}" \
--data-raw '
{
"articleBody": "Goo",
"title": "Baker"
}' \
--header "Content-Type: application/json" \
--request "PUT" \
--user "test@liferay.com:learn"
KnowledgeBaseArticle_PUT_ById.java
Command:
java -classpath .:* -DknowledgeBaseArticleId=1234 KnowledgeBaseArticle_PUT_ById
Code:
public static void main(String[] args) throws Exception {
KnowledgeBaseArticleResource.Builder builder =
KnowledgeBaseArticleResource.builder();
KnowledgeBaseArticleResource knowledgeBaseArticleResource =
builder.authentication(
"test@liferay.com", "learn"
).build();
KnowledgeBaseArticle knowledgeBaseArticle =
knowledgeBaseArticleResource.putKnowledgeBaseArticle(
Long.valueOf(System.getProperty("knowledgeBaseArticleId")),
new KnowledgeBaseArticle() {
{
articleBody = "Goo";
title = "Dog";
}
});
System.out.println(knowledgeBaseArticle);
}
Delete a Knowledge Base Article
Delete an existing Knowledge Base article with the following cURL and Java commands. Replace 1234
with your Knowledge Base article’s ID.
KnowledgeBaseArticle_DELETE_ById.sh
Command:
./KnowledgeBaseArticle_DELETE_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-delivery/v1.0/knowledge-base-articles/${1}" \
--request "DELETE" \
--user "test@liferay.com:learn"
KnowledgeBaseArticle_DELETE_ById.java
Command
java -classpath .:* -DknowledgeBaseArticleId=1234 KnowledgeBaseArticle_DELETE_ById
Code:
public static void main(String[] args) throws Exception {
KnowledgeBaseArticleResource.Builder builder =
KnowledgeBaseArticleResource.builder();
KnowledgeBaseArticleResource knowledgeBaseArticleResource =
builder.authentication(
"test@liferay.com", "learn"
).build();
knowledgeBaseArticleResource.deleteKnowledgeBaseArticle(
Long.valueOf(System.getProperty("knowledgeBaseArticleId")));
}
Knowledge Base Folder services
The cURL commands and Java classes for Knowledge Base folders works in the same way as Knowledge Base articles.
Files | Description |
---|---|
KnowledgeBaseFolder_DELETE_ById.[java\|sh] | Deletes a Knowledge Base folder by ID. |
KnowledgeBaseFolder_GET_ById.[java\|sh] | Get a specific Knowledge Base folder by ID. |
KnowledgeBaseFolder_PATCH_ById.[java\|sh] | Patch a Knowledge Base folder by ID. |
KnowledgeBaseFolder_POST_ToSite.[java\|sh] | Post a Knowledge Base folder to a site. |
KnowledgeBaseFolder_PUT_ToSite.[java\|sh] | Put a Knowledge Base folder by ID. |
KnowledgeBaseFolders_GET_FromSite.[java\|sh] | Get a list of Knowledge Base folders from a site. |
The API Explorer shows all of the KnowledgeBaseArticle
and KnowledgeBaseFolder
services and schemas and has an interface to try out each service.