Blog API Basics

Liferay’s REST APIs provide services for adding, modifying, and deleting blog posts and images.

Note

Liferay DXP 2024.Q4+/Portal GA129+ The Blogs API now uses External Reference Codes (ERCs) to reference blog posts and images, enabling consistent identification across instances and supporting batch export/import for improved content management and portability.

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.132-ga132

Sign in to Liferay at http://localhost:8080. Use the email address test@liferay.com 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/examples/liferay-r3g4.zip -O

unzip liferay-r3g4.zip

Find your site’s ID. It’s used 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 the BlogPostings_POST_ToSites.sh script with your site ID as a parameter.

./BlogPostings_POST_ToSites.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 the java folder. Compile the source files:
```
javac -classpath .:* *.java
```
Run the BlogPostings_POST_ToSites class. Replace the siteId value with your site ID:
```
java -classpath .:* -DsiteId=1234 BlogPostings_POST_ToSites
```

Examine the cURL Command

The BlogPostings_POST_ToSites.sh script calls the REST service with a cURL command.

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/blog-postings" \
	--data-raw '
		{
			"articleBody": "Foo",
			"headline": "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}/blog-postings"`	The REST service endpoint
`-d "{\"articleBody\": \"Foo\", \"headline\": \"Able\"}"`	The data you are requesting to post
`-u "test@liferay.com:learn"`	Basic authentication credentials

Note

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 BlogPostings_POST_ToSites.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(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		blogPostingResource.postSiteBlogPosting(
			Long.valueOf(System.getProperty("siteId")),
			new BlogPosting() {
				{
					articleBody = "Foo";
					headline = "Baker";
				}
			}));
}

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.

Note

The main method’s comment demonstrates running the class.

The other example Java classes are similar to this one, but call different BlogPostingResource methods.

Important

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_FromSites.sh

Command:

./BlogPostings_GET_FromSites.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/blog-postings" \
	--user "test@liferay.com:learn"

BlogPostings_GET_FromSites.java

Command:

java -classpath .:* -DsiteId=1234 BlogPostings_GET_FromSites

Code:

public static void main(String[] args) throws Exception {
	BlogPostingResource.Builder builder = BlogPostingResource.builder();

	BlogPostingResource blogPostingResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		blogPostingResource.getSiteBlogPostingsPage(
			Long.valueOf(System.getProperty("siteId")), null, null, null,
			Pagination.of(1, 2), null));
}

The GET method returns the site’s BlogPosting objects in JSON format.

Get a Blog Post

Get a specific blog post with the following cURL or Java command. Replace 1234 with the blog post’s ID.

Tip

Use BlogPostings_GET_FromSites.[java|sh] to get BlogPosting IDs.

BlogPostings_GET_ById.sh

Command:

./BlogPostings_GET_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/blog-postings/${1}" \
	--user "test@liferay.com:learn"

BlogPostings_GET_ById.java

Command:

java -classpath .:* -DblogPostingId=1234 BlogPostings_GET_ById

Code:

public static void main(String[] args) throws Exception {
	BlogPostingResource.Builder builder = BlogPostingResource.builder();

	BlogPostingResource blogPostingResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		blogPostingResource.getBlogPosting(
			Long.valueOf(System.getProperty("blogPostingId"))));
}

The GET method returns the BlogPosting fields in JSON format.

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.

BlogPostings_PATCH_ById.sh

Command:

./BlogPostings_PATCH_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/blog-postings/${1}" \
	--data-raw '
		{
			"articleBody": "Bar"
		}' \
	--header "Content-Type: application/json" \
	--request "PATCH" \
	--user "test@liferay.com:learn"

BlogPostings_PATCH_ById.java

Command:

java -classpath .:* -DblogPostingId=1234 BlogPostings_PATCH_ById

Code:

public static void main(String[] args) throws Exception {
	BlogPostingResource.Builder builder = BlogPostingResource.builder();

	BlogPostingResource blogPostingResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		blogPostingResource.patchBlogPosting(
			Long.valueOf(System.getProperty("blogPostingId")),
			new BlogPosting() {
				{
					articleBody = "Bar";
				}
			}));
}

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.

BlogPostings_PUT_ById.sh

Command:

./BlogPostings_PUT_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/blog-postings/${1}" \
	--data-raw '
		{
			"articleBody": "Goo",
			"headline": "Able"
		}' \
	--header "Content-Type: application/json" \
	--request "PUT" \
	--user "test@liferay.com:learn"

BlogPostings_PUT_ById.java

Command:

java -classpath .:* -DblogPostingId=1234 BlogPostings_PUT_ById

Code:

public static void main(String[] args) throws Exception {
	BlogPostingResource.Builder builder = BlogPostingResource.builder();

	BlogPostingResource blogPostingResource = builder.authentication(
		"test@liferay.com", "learn"
	).build();

	System.out.println(
		blogPostingResource.putBlogPosting(
			Long.valueOf(System.getProperty("blogPostingId")),
			new BlogPosting() {
				{
					articleBody = "Goo";
					headline = "Baker";
				}
			}));
}

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.

BlogPostings_DELETE_ById.sh

Command:

./BlogPostings_DELETE_ById.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/blog-postings/${1}" \
	--request "DELETE" \
	--user "test@liferay.com:learn"

BlogPostings_DELETE_ById.java

Command

java -classpath .:* -DblogPostingId=1234 BlogPostings_DELETE_ById

Code:

public static void main(String[] args) throws Exception {
	BlogPostingResource.Builder builder = BlogPostingResource.builder();

	BlogPostingResource blogPostingResource = builder.authentication(
		"test@liferay.com", "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
`BlogPostingImages_DELETE_ById.[java\\|sh]`	Deletes a blog post image by ID.
`BlogPostingImages_GET_ById.[java\\|sh]`	Get a specific blog post image by ID.
`BlogPostingImages_POST_ToSites.[java\\|sh]`	Post a blog post image to a site.
`BlogPostingImages_GET_FromSites.[java\\|sh]`	Get a list of blog post images from a site.