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.112-ga112

Sign in to Liferay at http://localhost:8080. Use the email address [e-mail] and the password test. When prompted, change the password to learn.

Then, follow these steps:

1. 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
   

2. Find your Site’s ID. You’ll use this in different service calls below.

3. Use the cURL script to add a new blog post to your Site. On the command line, navigate to the curl folder. Execute the BlogPosting_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": []
   }
   

4. Go to the Blogs application by navigating to Administration Menu → Content & Data → Blogs. See that a new blog post has been added.

   

5. 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
   

6. Run the BlogPosting_POST_ToSite class. Replace the siteId 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 \
	"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 "[e-mail]: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 "[e-mail]: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 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(
		"[e-mail]", "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.

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

Command:

./BlogPostings_GET_FromSite.sh 1234

Code:

curl \
	"http://localhost:8080/o/headless-delivery/v1.0/sites/${1}/blog-postings" \
	--user "[e-mail]: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(
		"[e-mail]", "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.

tip

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}" \
	--user "[e-mail]: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(
		"[e-mail]", "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 \
	"http://localhost:8080/o/headless-delivery/v1.0/blog-postings/${1}" \
	--data-raw '
		{
			"articleBody": "Bar"
		}' \
	--header "Content-Type: application/json" \
	--request "PATCH" \
	--user "[e-mail]: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(
		"[e-mail]", "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 \
	"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 "[e-mail]: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(
		"[e-mail]", "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 \
	"http://localhost:8080/o/headless-delivery/v1.0/blog-postings/${1}" \
	--request "DELETE" \
	--user "[e-mail]: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(
		"[e-mail]", "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.