Message Boards API Basics

Liferay’s Headless Delivery application provides REST services for the Message Boards application. With these services, you can add message board categories, threads, and messages, list their information, modify their content, or remove them altogether. Access these services using methods such as cURL commands and Java classes.

Note

Message board categories are named sections in the Liferay backend. These sections define topics for organizing threads.

Preparing Message Boards Resources

Before proceeding with the tutorial, set up a clean Liferay Docker container and prepare the provided tutorial code for use.

Liferay Docker Container

Start a new Liferay instance by running

docker run -it -m 8g -p 8080:8080 liferay/portal:7.4.3.120-ga120

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.

Once started, retrieve the site ID. To find your site ID, open the Site Menu (Site Menu) and go to ConfigurationSite SettingsSite Configuration.

Find the site ID under the Site Configuration settings.

Tutorial Code

Below is the sample code to demonstrate the headless API. This code includes both sample cURL and Java files.

Run the following command to download and unzip the sample code:

curl https://resources.learn.liferay.com/dxp/latest/en/collaboration-and-social/message-boards/developer-guide/liferay-y3a6.zip -O
unzip liferay-y3a6.zip

While the cURL scripts come ready for use, you must compile the Java source files manually before you run them. To do this, go to the project’s java folder and run the javac command.

cd liferay-y3a6/java
javac -classpath .:* *.java

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 provided code includes APIs for the MessageBoardSection, MessageBoardThread and MessageBoardMessage services. See Tutorial Code Reference for a list of all included sample APIs.

Important

The provided code uses basic authentication for demonstration purposes. For production, you should authorize users with OAuth2.

Calling the Message Boards APIs

In this exercise, you can use either the cURL commands or Java classes to call the MessageBoardSection, MessageBoardThread and MessageBoardMessage APIs. The following output examples correspond to the cURL commands, which differ slightly from the output for the provided Java classes.

  1. Navigate to the curl or java folder in the liferay-y3a6 project.

    For cURL:

    cd liferay-y3a6/curl
    

    For Java:

    cd liferay-y3a6/java
    
  2. Execute MessageBoardSection_POST_ToSite using your site ID as a parameter. This creates a new message board section in the specified site.

    For cURL:

    ./MessageBoardSection_POST_ToSite.sh {site-id}
    

    For Java:

    java -classpath .:* -DsiteId={site-id} MessageBoardSection_POST_ToSite
    

    The terminal displays the complete schema for the newly created section. The provided API calls only define the description and name fields for the new section.

  3. Copy the section’s ID for use with the following GET, PATCH, PUT, and DELETE methods.

    {
       ...
       "description" : "Foo",
       "id" : 43925,
       ...
       "name" : "Able Section",
       ...
    }
    
  4. Execute MessageBoardSections_GET_FromSite using the site ID for its parameter. This returns a list of all sections in the specified site.

    For cURL:

    ./MessageBoardSections_GET_FromSite.sh {site-id}
    

    For Java:

    java -classpath .:* -DsiteId={site-id} MessageBoardSections_GET_FromSite
    
  5. Execute MessageBoardSection_PATCH_ById using the message board section’s ID for its parameter. This updates the details of the specified section with those provided in the API call.

    For cURL:

    ./MessageBoardSection_PATCH_ById.sh {message-board-section-id}
    

    For Java:

    java -classpath .:* -DmessageBoardSectionId={message-board-section-id} MessageBoardSection_PATCH_ById
    

    This updates the description field to Bar.

  6. Execute MessageBoardSection_PUT_ById using the same section ID for its parameter. This replaces the details of the specified section with those provided in the API call.

    For cURL:

    ./MessageBoardSection_PUT_ById.sh {message-board-section-id}
    

    For Java:

    java -classpath .:* -DmessageBoardSectionId={message-board-section-id} MessageBoardSection_PUT_ById
    

    This updates the name field to Baker Section and the description field to Goo.

  7. Execute MessageBoardThread_POST_ToSite using the site ID for its parameter. This creates a new message board thread for the site.

    For cURL:

    ./MessageBoardThread_POST_ToSite.sh {site-id}
    

    For Java:

    java -classpath .:* -DsiteId={site-id} MessageBoardThread_POST_ToSite
    
    {
       ...
       "articleBody" : "Foo",
       ...
       "headline" : "Able Thread",
       "id" : 43942,
       ...
       "messageBoardRootMessageId" : 43941,
    }
    

    All threads are created with a root message that serves as the parent message of all direct replies in the thread (i.e., messageBoardRootMessageId).

  8. Execute MessageBoardThread_POST_ToSection using the above section ID for its parameter. This creates a new message board thread for the specified section.

    For cURL:

    ./MessageBoardThread_POST_ToSection.sh {message-board-section-id}
    

    For Java:

    java -classpath .:* -DmessageBoardSectionId={message-board-section-id} MessageBoardThread_POST_ToSection
    
  9. Copy this thread’s ID for use with the following GET, PATCH, and PUT methods.

    {
       ...
       "articleBody" : "Foo",
       ...
       "headline" : "Baker Thread",
       "id" : 43934,
       ...
       "messageBoardRootMessageId" : 43933,
       "messageBoardSectionId" : 43925,
       ...
    }
    
  10. Execute MessageBoardThread_PATCH_ById using the thread’s ID for its parameter. This updates the details of the specified thread with those provided in the API call.

    For cURL:

    ./MessageBoardThread_PATCH_ById.sh {message-board-thread-id}
    

    For Java:

    java -classpath .:* -DmessageBoardThreadId={message-board-thread-id} MessageBoardThread_PATCH_ById
    

    This updates the articleBody field to Bar.

  11. Execute MessageBoardThread_PUT_ById using the same thread ID for its parameter. This replaces the details of the specified thread with those provided in the API call.

    For cURL:

    ./MessageBoardThread_PUT_ById.sh {message-board-thread-id}
    

    For Java:

    java -classpath .:* -DmessageBoardThreadId={message-board-thread-id} MessageBoardThread_PUT_ById
    

    This updates the headline field to Charlie Thread and the articleBody field to Goo.

  12. Execute the MessageBoardThreads_GET_FromSite using the site ID for its parameter. This returns a list of all site threads without a section.

    For cURL:

    ./MessageBoardThreads_GET_FromSite.sh {site-id}
    

    For Java:

    java -classpath .:* -DsiteId={site-id} MessageBoardThreads_GET_FromSite
    
  13. Execute MessageBoardThreads_GET_FromSection using the section ID for its parameter. This returns a list of all threads in the specified section.

    For cURL:

    ./MessageBoardThreads_GET_FromSection.sh {message-board-section-id}
    

    For Java:

    java -classpath .:* -DmessageBoardSectionId={message-board-section-id} MessageBoardThreads_GET_FromSection
    
  14. Execute MessageBoardMessage_POST_ToThread using either of the above thread IDs for its parameter. This creates a new message board message for the specified thread.

    For cURL:

    ./MessageBoardMessage_POST_ToThread.sh {message-board-thread-id}
    

    For Java:

    java -classpath .:* -DmessageBoardThreadId={message-board-thread-id} MessageBoardMessage_POST_ToThread
    
  15. Copy the message’s ID for use with the following PUT, PATCH, and POST commands.

    {
       ...
       "articleBody" : "Foo",
       ...
       "headline" : "Able Message",
       "id" : 43946,
       ...
       "messageBoardSectionId" : 43925,
       "messageBoardThreadId" : 43934,
       "parentMessageBoardMessageId" : 43933,
       ...
    }
    

    The new message is created as a child of the thread’s root message (messageBoardRootMessageId).

  16. Execute MessageBoardMessage_PATCH_ById using the message’s ID for its parameter. This updates the details of the specified message with those provided in the API call.

    For cURL:

    ./MessageBoardMessage_PATCH_ById.sh {message-board-message-id}
    

    For Java:

    java -classpath .:* -DmessageBoardMessageId={message-board-message-id} MessageBoardMessage_PATCH_ById
    

    This updates the articleBody field to Bar.

  17. Execute MessageBoardMessage_PUT_ById using the same message ID for its parameter. This replaces the details of the specified message with those provided in the API call.

    For cURL:

    ./MessageBoardMessage_PUT_ById.sh {message-board-message-id}
    

    For Java:

    java -classpath .:* -DmessageBoardMessageId={message-board-message-id} MessageBoardMessage_PUT_ById
    

    This updates the headline field to Baker Message and the articleBody field to Goo.

  18. Execute MessageBoardMessage_POST_ToParent using the preceding message ID for its parameter. This creates a new child message for the specified message.

    For cURL:

    ./MessageBoardMessage_POST_ToParent.sh {parent-message-board-message-id}
    

    For Java:

    java -classpath .:* -DparentMessageBoardMessageId={parent-message-board-message-id} MessageBoardMessage_POST_ToParent
    
    {
       ...
       "articleBody" : "Foo",
       ...
       "headline" : "Charlie Message",
       "id" : 43949,
       ...
       "messageBoardSectionId" : 43925,
       "messageBoardThreadId" : 43934,
       ...
       "parentMessageBoardMessageId" : 43946,
       ...
    }
    
  19. Execute MessageBoardMessages_GET_FromThread using the thread ID for its parameter. This returns a list of child messages for the thread’s root message (i.e., messageBoardRootMessage).

    For cURL:

    ./MessageBoardMessages_GET_FromThread.sh {message-board-thread-id}
    

    For Java:

    java -classpath .:* -DmessageBoardThreadId={message-board-thread-id} MessageBoardMessages_GET_FromThread
    

    The output should include data for the first message you created in the thread, which should itself have one child message. This is indicated by the message’s numberOfMessageBoardMessages field.

  20. Execute MessageBoardMessages_GET_FromParent using the preceding message’s ID for its parameter. This returns a list of all child messages for the specified Message.

    For cURL:

    ./MessageBoardMessages_GET_FromParent.sh {parent-message-board-message-id}
    

    For Java:

    java -classpath .:* -DparentMessageBoardMessageId={parent-message-board-message-id} MessageBoardMessages_GET_FromParent
    

    The output should include data for the last child message you created.

  21. Execute MessageBoardSection_DELETE_ById using the same section ID for its parameter. This deletes the specified section along with its threads and messages.

    For cURL:

    ./MessageBoardSection_DELETE_ById.sh {message-board-section-id}
    

    For Java:

    java -classpath .:* -DmessageBoardSectionId={message-board-section-id} MessageBoardSection_DELETE_ById
    
  22. Execute MessageBoardSection_GET_ById using the same section ID for its parameter. This returns the details for the specified section if it exists.

    For cURL:

    ./MessageBoardSection_GET_ById.sh {message-board-section-id}
    

    For Java:

    java -classpath .:* -DmessageBoardSectionId={message-board-section-id} MessageBoardSection_GET_ById
    

    Since you deleted the section in the preceding step, it returns the following message.

    {
       "status" : "NOT_FOUND",
       "title" : "No MessageBoardSection exists with the primary key 43925"
    }
    

Code Reference

The provided sample code includes cURL scripts and Java classes for the following MessageBoardSection, MessageBoardThread and MessageBoardMessage APIs.

Sample MessageBoardSection APIs

The sample code includes cURL scripts and Java classes that call the following APIs.

ServiceHTTP MethodHTTP EndpointDescription
MessageBoardSectionPOST/v1.0/sites/[siteId]/message-board-sectionsCreates a new category with the details provided in the API call
MessageBoardSectionGET/v1.0/sites/[siteId]/message-board-sectionsReturns a complete list of all categories in the specified site; results can be paginated, filtered, searched, and sorted
MessageBoardSectionPATCH/v1.0/message-board-sections/[messageBoardSectionId]Updates only the fields specified in the API call for a category
MessageBoardSectionPUT/v1.0/message-board-sections/[messageBoardSectionId]Replaces all fields for the specified category with those provided in the API call
MessageBoardSectionDELETE/v1.0/message-board-sections/[messageBoardSectionId]Deletes the specified category and returns a 204 if the operation succeeds

Sample MessageBoardThread APIs

ServiceHTTP MethodHTTP EndpointDescription
MessageBoardThreadPOST/v1.0/sites/[siteId]/message-board-threadsCreates a new thread with the details provided in the API call
MessageBoardThreadPOST/v1.0/message-board-sections/[messageBoardSectionId]/message-board-threadsCreates a new thread within the specified category using the details provided in the API call
MessageBoardThreadGET/v1.0/sites/[siteId]/message-board-threadsReturns a complete list of all site threads that are not in a category; results can be paginated, filtered, searched, and sorted
MessageBoardThreadGET/v1.0/message-board-sections/[messageBoardSectionId]/message-board-threadsReturns a complete list of all threads in the specified category; results can be paginated, filtered, searched, and sorted
MessageBoardThreadPATCH/v1.0/message-board-threads/[messageBoardThreadId]Updates only the fields specified in the API call for a thread
MessageBoardThreadPUT/v1.0/message-board-threads/[messageBoardThreadId]Replaces all fields for the specified thread with those provided in the API call
MessageBoardThreadDELETE/v1.0/message-board-threads/[messageBoardThreadId]Deletes the specified thread and returns a 204 if the operation succeeds

Sample MessageBoardMessage APIs

ServiceHTTP MethodHTTP EndpointDescription
MessageBoardMessagePOST/v1.0/message-board-threads/[messageBoardThreadId]/message-board-messagesCreates a new message in the specified thread with the detailed provided in the API call.
MessageBoardMessageGET/v1.0/message-board-threads/[messageBoardThreadId]/message-board-messagesReturns a complete list of all messages in the specified thread; results can be paginated, filtered, searched, and sorted
MessageBoardMessagePATCH/v1.0/message-board-messages/[messageBoardMessageId]Updates only the fields specified in the API call for a message
MessageBoardMessagePUT/v1.0/message-board-messages/[messageBoardMessageId]Replaces all fields for the specified message with those provided in the API call
MessageBoardMessageDELETE/v1.0/message-board-messages/[messageBoardMessageId]Deletes the specified message and returns a 204 if the operation succeeds

Capabilities

Product

Contact Us

Connect

Powered by Liferay
© 2024 Liferay Inc. All Rights Reserved • Privacy Policy