Blog API Basics
Liferay’s REST API’s provide services for adding, modifying, and deleting blog posts and images.
Start by seeing an example of adding a new blog post.
Adding a Blog Post
Start a new Liferay instance by running
docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.55-ga55
Sign in to Liferay at http://localhost:8080. Use the email address [email protected] and the password test. When prompted, change the password to learn.
Then, follow these steps:
Download and unzip Blog API Basics.
curl https://resources.learn.liferay.com/dxp/latest/en/content-authoring-and-management/blogs/developer-guide/liferay-r3g4.zip -O
unzip liferay-r3g4.zip
Find your Site’s ID. You’ll use this in different service calls below.
Use the cURL script to add a new blog post to your Site. On the command line, navigate to the
curl
folder. Execute theBlogPosting_POST_ToSite.sh
script with your Site ID as a parameter../BlogPosting_POST_ToSite.sh 1234
The JSON response shows a new blog post has been added:
"alternativeHeadline" : "", "articleBody" : "Foo", "creator" : { "additionalName" : "", "contentType" : "UserAccount", "familyName" : "Test", "givenName" : "Test", "id" : 20125, "name" : "Test Test" }, "customFields" : [ ], "dateCreated" : "2021-07-21T21:26:55Z", "dateModified" : "2021-07-21T21:26:55Z", "datePublished" : "2021-07-21T21:26:00Z", "description" : "", "encodingFormat" : "text/html", "friendlyUrlPath" : "able", "headline" : "Able", "id" : 38511, "keywords" : [ ], "numberOfComments" : 0, "relatedContents" : [ ], "siteId" : 20121, "taxonomyCategoryBriefs" : [ ]
Go to the Blogs application by navigating to Administration Menu → Content & Data → Blogs. See that a new blog post has been added.
The REST service can also be called with a Java class. Navigate out of the
curl
folder and into thejava
folder. Compile the source files:javac -classpath .:* *.java
Run the
BlogPosting_POST_ToSite
class. Replace thesiteId
value with your site’s ID:java -classpath .:* -DsiteId=1234 BlogPosting_POST_ToSite
Examine the cURL Command
The BlogPosting_POST_ToSite.sh
script calls the REST service with a cURL command.
curl \
-H "Content-Type: application/json" \
-X POST \
"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/blog-postings" \
-d "{\"articleBody\": \"Foo\", \"headline\": \"Able\"}" \
-u "[email protected]: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}/blog-postings" |
The REST service endpoint |
-d "{\"articleBody\": \"Foo\", \"headline\": \"Able\"}" |
The data you are requesting to post |
-u "[email protected]: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 BlogPosting_POST_ToSite.java
class adds a blog post by calling the blog posting related service.
public static void main(String[] args) throws Exception {
BlogPostingResource.Builder builder = BlogPostingResource.builder();
BlogPostingResource blogPostingResource = builder.authentication(
"[email protected]", "learn"
).build();
BlogPosting blogPosting = blogPostingResource.postSiteBlogPosting(
Long.valueOf(System.getProperty("siteId")),
new BlogPosting() {
{
articleBody = "Foo";
headline = "Baker";
}
});
System.out.println(blogPosting);
}
This class invokes the REST service using only three lines of code:
Line (abbreviated) | Description |
---|---|
BlogPostingResource.Builder builder = ... |
Gets a Builder for generating a BlogPostingResource service instance. |
BlogPostingResource blogPostingResource = builder.authentication(...).build(); |
Specifies basic authentication and generates a BlogPostingResource service instance. |
BlogPosting blogPosting = blogPostingResource.postSiteBlogPosting(...); |
Calls the BlogPostingResource.postSiteBlogPosting 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 BlogPostingResource
methods.
See BlogPostingResource for service details.
Below are examples of calling other BlogPosting
REST services using cURL and Java.
Get Blog Posts from Site
You can list a site’s blog posts by executing the following cURL or Java command. As above, replace 1234
with your site’s ID.
BlogPostings_GET_FromSite.sh
Command:
./BlogPostings_GET_FromSite.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/blog-postings" \
-u "[email protected]:learn"
BlogPostings_GET_FromSite.java
Command:
java -classpath .:* -DsiteId=1234 BlogPostings_GET_FromSite
Code:
public static void main(String[] args) throws Exception {
BlogPostingResource.Builder builder = BlogPostingResource.builder();
BlogPostingResource blogPostingResource = builder.authentication(
"[email protected]", "learn"
).build();
Page<BlogPosting> page = blogPostingResource.getSiteBlogPostingsPage(
Long.valueOf(System.getProperty("siteId")), null, null, null,
Pagination.of(1, 2), null);
System.out.println(page);
}
The site’s BlogPosting
objects are listed in JSON.
Get a Blog Post
Get a specific blog post with the following cURL or Java command. Replace 1234
with the blog post’s ID.
Use BlogPostings_GET_FromSite.[java|sh]
to get BlogPosting
IDs.
BlogPosting_GET_ById.sh
Command:
./BlogPosting_GET_ById.sh 1234
Code:
curl \
"http://localhost:8080/o/headless-delivery/v1.0/blog-postings/${1}" \
-u "[email protected]:learn"
BlogPosting_GET_ById.java
Command:
java -classpath .:* -DblogPostingId=1234 BlogPosting_GET_ById
Code:
public static void main(String[] args) throws Exception {
BlogPostingResource.Builder builder = BlogPostingResource.builder();
BlogPostingResource blogPostingResource = builder.authentication(
"[email protected]", "learn"
).build();
System.out.println(
blogPostingResource.getBlogPosting(
Long.valueOf(System.getProperty("blogPostingId"))));
}
The BlogPosting
fields are listed in JSON.
Patch a Blog Post
Do a partial edit of an existing blog post with the following cURL and Java commands. Note: replace 1234
with your blog post’s ID.
BlogPosting_PATCH_ById.sh
Command:
./BlogPosting_PATCH_ById.sh 1234
Code:
curl \
-H "Content-Type: application/json" \
-X PATCH \
"http://localhost:8080/o/headless-delivery/v1.0/blog-postings/${1}" \
-d "{\"articleBody\": \"Bar\"}" \
-u "[email protected]:learn"
BlogPosting_PATCH_ById.java
Command:
java -classpath .:* -DblogPostingId=1234 BlogPosting_PATCH_ById
Code:
public static void main(String[] args) throws Exception {
BlogPostingResource.Builder builder = BlogPostingResource.builder();
BlogPostingResource blogPostingResource = builder.authentication(
"[email protected]", "learn"
).build();
BlogPosting blogPosting = blogPostingResource.patchBlogPosting(
Long.valueOf(System.getProperty("blogPostingId")),
new BlogPosting() {
{
articleBody = "Bar";
}
});
System.out.println(blogPosting);
}
In this example the article body content is changed from Foo to Bar.
Put a Blog Post
Do a complete overwrite of an existing blog post with the following cURL and Java commands. Note, replace 1234
with your blog post’s ID.
BlogPosting_PUT_ById.sh
Command:
./BlogPosting_PUT_ById.sh 1234
Code:
curl \
-H "Content-Type: application/json" \
-X PUT \
"http://localhost:8080/o/headless-delivery/v1.0/blog-postings/${1}" \
-d "{\"articleBody\": \"Goo\", \"headline\": \"Able\"}" \
-u "[email protected]:learn"
BlogPosting_PUT_ById.java
Command:
java -classpath .:* -DblogPostingId=1234 BlogPosting_PUT_ById
Code:
public static void main(String[] args) throws Exception {
BlogPostingResource.Builder builder = BlogPostingResource.builder();
BlogPostingResource blogPostingResource = builder.authentication(
"[email protected]", "learn"
).build();
BlogPosting blogPosting = blogPostingResource.putBlogPosting(
Long.valueOf(System.getProperty("blogPostingId")),
new BlogPosting() {
{
articleBody = "Goo";
headline = "Baker";
}
});
System.out.println(blogPosting);
}
Delete a Blog Post
Delete an existing blog post with the following cURL and Java commands. Note, replace 1234
with your blog post’s ID.
BlogPosting_DELETE_ById.sh
Command:
./BlogPosting_DELETE_ById.sh 1234
Code:
curl \
-X DELETE \
"http://localhost:8080/o/headless-delivery/v1.0/blog-postings/${1}" \
-u "[email protected]:learn"
BlogPosting_DELETE_ById.java
Command
java -classpath .:* -DblogPostingId=1234 BlogPosting_DELETE_ById
Code:
public static void main(String[] args) throws Exception {
BlogPostingResource.Builder builder = BlogPostingResource.builder();
BlogPostingResource blogPostingResource = builder.authentication(
"[email protected]", "learn"
).build();
blogPostingResource.deleteBlogPosting(
Long.valueOf(System.getProperty("blogPostingId")));
}
Blog Post Image Services
The cURL commands and Java classes for blog images works in the same way as blog posts.
Files | Description |
---|---|
BlogPostingImage_DELETE_ById.[java\|sh] |
Deletes a blog post image by ID. |
BlogPostingImage_GET_ById.[java\|sh] |
Get a specific blog post image by ID. |
BlogPostingImage_POST_ToSite.[java\|sh] |
Post a blog post image to a site. |
BlogPostingImages_GET_FromSite.[java\|sh] |
Get a list of blog post images from a site. |
The API Explorer lists all of the BlogPosting
and BlogPostingImage
services and schemas, and has an interface to try out each service.