Using Headless APIs

Clarity wants to use leverage Liferay’s headless APIs to import content from their legacy systems. They also want to leverage headless APIs to import Clarity products from their Product Information Management system (PMI).

Exercise: Connecting to Headless APIs Using the API Explorer

Let’s see how headless APIs can be used by interacting with it through Liferay’s API Explorer. Here you’ll add a new blog post as Walter Douglas.

To do this,

1. Open the Site Menu (), expand Configuration, and select Site Settings.

2. Select Site Configuration under Platform.

3. Copy down the Site ID and save it for a future step.

4. Open the Site Menu (), expand Categorization, and select Categories.

5. Click Blog Posts under the Clarity vocabularies.

6. Select one of the categories in the list.

7. In your browser’s navigation bar, copy down the category’s ID that appears in the page URL. For example, (...)categories_admin/vocabulary/37819/category/[category-id]. You’ll use this ID in a later step.

8. Open a new browser window and access Liferay’s API Explorer at http://localhost:8080/o/api.

9. Scroll down to the Document section and expand the postSiteDocument endpoint.

   Tip: To quickly find the endpoint, search the browser page for postSiteDocument.

   

10. For the siteId field, enter the site ID for Clarity Public Enterprise Website.

11. For the document field, delete the default JSON content and uncheck Send empty value.

12. For file field, click Choose File and select glasses-book.png from the [repository-folder]/exercises/lesson-15/ folder.

13. Click Execute.

    This uploads a new image file to Clarity’s Documents and Media.

14. In the response body, look for the image’s ID. For example:

    (...)
    "fileExtension" : "png",
    "fileName" : "glasses-book.png",
    "id" : [image-id],
    "keywords" : [ ],
    (...)
    

    Copy down the image ID to use in the next step.

15. Scroll up to the BlogPosting section and expand the postSiteBlogPosting endpoint.

16. For siteId, enter the site ID for Clarity Public Enterprise Website.

17. For Request Body, delete the default JSON content.

18. From the training workspace, open the blog-entry.json file in the [repository-folder]/exercises/lesson-15/ folder.

    This file contains a blog post entry with a custom headline and body content.

19. Copy the contents of blog-entry.json into the Request Body field.

20. Replace {image-id} and {category-id} with your image ID and the blog category ID, respectively.

21. Click Execute. Make sure the response code is 200.

22. Return to the Clarity Public Enterprise Website window, open the Site Menu (), expand Content & Data, and click Blogs.

23. Confirm the Things I Find Interesting in Eyewear blog post appears.

    

Exercise: Using Headless APIs to Batch Import Web Content

Clarity wants to import three legacy web articles from their old portal into their new enterprise website. Here you’ll add them using Liferay’s Headless APIs as Walter Douglas.

To do this,

1. Return to the browser window for Liferay’s API Explorer (http://localhost:8080/o/api).

2. Scroll down to the StructuredContent section and expand the postSiteStructuredContentBatch endpoint.

3. For siteId, enter the site ID for Clarity Public Enterprise Website.

4. For Request Body, delete the default JSON content.

5. From the training workspace, open the import-web-content-articles-batch.json file in the [repository-folder]/exercises/lesson-15/ folder.

6. Copy the contents of import-web-content-articles-batch.json into the Request Body field.

7. Click Execute.

8. Return to the Clarity Public Enterprise Website window, open the Site Menu (), expand Content & Data, and click Web Content.

9. Open the Articles folder and confirm all three articles appear.

   

Exercise: Using Headless APIs to Batch Import Products

You can use REST APIs to import Clarity’s products from external systems to Liferay DXP, streamlining product management. Here you’ll use APIs to create products as Ian Miller.

To do this,

1. Sign in as Ian Miller.

   • Username: [e-mail]
   • Password: learn

2. Open the Global Menu (), go to the Commerce tab, and click Products.

   Take note of the number of existing products (i.e. 3).

3. Open the Global Menu (), go to the Commerce tab, and click Catalogs.

4. Click Clarity Eyewear.

   Copy down the catalog’s ID. You’ll use it in a later step.

5. Open a new browser window and access Liferay’s API Explorer at http://localhost:8080/o/api.

6. Click the REST Applications drop-down menu and select headless-commerce-admin-catalog/v1.0.

7. Scroll down to the Product section and expand the postProductBatch endpoint.

8. For Request Body, delete the default JSON content.

9. From the training workspace, open the import-products-batch.json file in the [repository-folder]/exercises/lesson-15/ folder.

10. Copy the contents of import-products-batch.json into the Request Body field and replace {catalog-id} for all products with the Clarity Eyewear catalog ID.

11. Click Execute.

12. Return to the Clarity Public Enterprise Website window, open the Global Menu (), go to the Commerce tab, and click Products.

13. Confirm eight new products appear.

    

Exercise: Using Headless to Import Taxonomy Categories

As a multinational company, Clarity has many business locations around the globe. To better support recruitment efforts, Clarity needs to define categories that they can apply to job openings for each office location. Some categories already exist, but others are still missing.

Here you’ll add the missing location categories as Clarity Admin.

To do this,

1. Sign in as the Clarity Admin user.

   • Username: [e-mail]
   • Password: learn

2. Open the Global Menu (), go to the Applications tab, and click Asset Libraries.

3. Select the HR library and click Categories.

4. Go to the Location vocabulary in the left side menu.

   Take note of the number of existing location categories (i.e. 14).

5. In your browser’s navigation bar, copy down the vocabulary’s ID that appears in the page URL. For example, (...)categories_admin/vocabulary/[vocabulary-id]. You’ll use this ID in a later step.

6. Open a new browser window and access Liferay’s API Explorer at http://localhost:8080/o/api.

7. Click the REST Applications drop-down menu and select headless-admin-taxonomy/v1.0.

8. Scroll down to the TaxonomyCategory section and expand the postTaxonomyVocabularyTaxonomyCategoryBatch endpoint.

9. For taxonomyVocabularyId, enter the vocabulary ID for Location.

10. For Request Body, delete the default JSON content.

11. From the training workspace, open the import-taxonomy-categories-batch.json file in the [repository-folder]/exercises/lesson-15/ folder.

12. Copy the contents of import-taxonomy-categories-batch.json into the Request Body field.

    

13. Click Execute.

14. Return to the HR Asset Library window and refresh the page.

    The new locations should appear.

15. Click HR in the breadcrumb menu to return to the library overview page.

16. Click Web Content and open the Job Listings folder.

17. Begin editing an article and assign any of the newly added locations (e.g. Morocco, Casablanca).

18. Click Publish. You can now search for the content using the new location category.

Conclusion

Congratulations, you’ve completed Module 8: Headless APIs. Throughout this module, you’ve seen different use cases for using Headless APIs and how a company like Clarity can leverage them to migrate existing data.

Next, let’s explore how Clarity can leverage Liferay’s search tools and capabilities to improve user experience.

Up Next: Module 9: Search

Additional Resources

See official documentation to learn more about using Liferay’s headless APIs:

• Consuming APIs
• Consuming REST Services
• Batch Engine API Basics - Importing Data