Overview

Skill Level: Any

This getting started tutorial walks you through a simple scenario to retrieve a content item by ID from the delivery content service and the authoring content service. You’ll learn how to call unauthenticated and authenticated APIs. By the end of the tutorial, you can make your own calls and retrieve responses from the Acoustic Content APIs.

Prerequisites

Get familiar with the Acoustic Content APIs

  • Acoustic Content offers you REST-based APIs to create, manage, and deliver your content. For example, use the authoring services API to create and manage content and the delivery services API to integrate content into your applications.
  • The Acoustic Content REST-based APIs can be called from standard browser-based xmlHttpRequest (xhr) support.
  • The format of the Acoustic Content REST API URLs is {API URL}/{WCH API endpoint}.

 The API URL is constructed as Domain name/{path} where {path}= api/{Content hub ID}.

The API endpoints are described in the Acoustic Content API documentation. For example, use endpoint “/delivery/v1/content/{Item ID}” or endpoint “/authoring/v1/content/{Item ID}” to access content items.

  • Most of the APIs require you to authenticate through the “/login/v1/basicauth” endpoint before you can access them except for delivery APIs, which are available to anonymous, unauthenticated callers.

 Example : To retrieve  a published content item by ID

  1. Get the Item ID from the Acoustic Content user interface. Open the specific content item that you want and click the API information icon below the content.

    ItemId = “b7abe31d-7763-41a9-b8d5-f7cf78565cbd”

  2. Provide the Item ID in the delivery API: {APIURL}/delivery/v1/content/{Item ID}.

https://my12.digitalexperience.ibm.com/api/12345678-…-56789abcdef0/delivery/v1/content/’b7abe31d-7763-41a9-b8d5-f7cf78565cbd’

For more information about Acoustic Content and all the available Acoustic Content developer tutorials, click here.

Step-by-step

  1. Get the API URL for your tenant

    You can get your API URL for your tenant from the Acoustic Content Authoring UI.

    1. From the Ribbon click About.
    2. Click Hub information. The API URL is displayed in the Hub information window. Your tenant API URL would look similar to:

      APIURL : https://{Domain name}/api/{ContenthubID}

    For example,  https://my12.digitalexperience.ibm.com/api/12345678-9abc-def0-1234-56789abcdef0.

    For more information about getting your base API URL specific to your Acoustic Content tenant, see API Explorer.

  2. Use the sample Acoustic Content API JS helper to retrieve content from delivery content service

    The sample wchhelper.js provides a simple wrapper that you can use to construct an instance of the helper for a specific tenant API URL. The sample wchhelper.js makes the REST API calls, handles the xhr request, and the JSON parsing of the response for you.

    1. Download the sample wchhelper.js helper to a local web application project file as js/wchhelper.js
    2. Load it with <script src=”js/wchhelper.js”>
    3. Construct an instance of the sample helper with the tenant-specific API URL. For example:

      let options = {
      ¬†¬†¬†¬† url: “https://{Domain name}/api/{Content hub ID}”,
          debug: true
      };
      wchHelper = new WchHelper(options);

    4. Use the helper to retrieve and display the JSON response for a content item. For example:

      contentId = ‘b7abe31d-7763-41a9-b8d5-f7cf78565cbd’;
      wchHelper.getDeliveryContentById(contentId)
      ¬†¬†¬†¬†¬†¬† .then(content => { alert(“Delivery Content response: ” + JSON.stringify(content, null, ‘ ‘)) })
      ¬†¬†¬†¬†¬†¬† .catch(err => { alert(“getDeliveryContentById encountered an error: ” + err); });

  3. Use the sample Acoustic Content API JS helper to log in and retrieve content from authoring content service

    You must log in to the Acoustic Content to use the Authoring service API as an authenticated user with a role as Editor, Manager, or Admin. You can use the sample wchhelper.js to log in.

    1. Construct an instance of the sample helper with the tenant-specific API URL. For example:

      let options = {
      ¬†¬†¬†¬† url: “https://{Domain name}/api/{Content hub ID}”,
           debug: true
      };
      wchHelper = new WchHelper(options);

    2. Make a call and pass the user name and password for the Acoustic Content user to log in.
    3. After successfully logging in, the wchhelper.js calls to retrieve and display the JSON response for an authoring content item. For example:

      contentId = ‘b7abe31d-7763-41a9-b8d5-f7cf78565cbd’;
      wchHelper.login(‘myWCHuser@mydomain.com’, ‘myPassword’)
              .then(tenantId => wchHelper.getAuthoringContentById(contentId))
      ¬†¬†¬†¬†¬†¬†¬† .then(acontent => { alert(“Authoring Content response: ” + JSON.stringify(acontent, null, ‘ ‘)) })
      ¬†¬†¬†¬†¬†¬†¬† .catch(err => { alert(“getAuthoringContentById encountered an error: ” + err); });

Expected outcome

For more information about Acoustic Content and all the available Acoustic Content developer tutorials, click here.

3 comments on"Getting Started with Acoustic Content APIs (JavaScript)"

  1. SHREE_ACN May 12, 2017

    Hi Team,

    Objective : To integrate the content Hub with eCommerce search mechanism on Portal.

    After trial registration I have downloaded the and trying to search but getting errors :
    I am using below URL –
    https://my13.digitalexperience.ibm.com/api/24ebda47-297e-4b3e-b147-09603372445a

    I have configured Username / Password and Tenant ID which I got after submitting request via Postman. ( Above )

    Can you please help us with more detailed steps to plug this Content Hub in portal.

    Regards,
    Shrikant
    7218996693

    • SharmilaM May 15, 2017

      Hello Shrikant,
      I would suggest you post this question in the WCH forum at Watson Content Hub forum: https://developer.ibm.com/answers/smartspace/wch/ where more WCH integration experts will be available to answer your question.
      Regards,
      Sharmila

  2. Michael Burati May 16, 2017

    Shrikant,
    In addition to Sharmila’s suggestion to discuss this in the WCH forum at the URL she posted above, (this comment section is specific to comments about this article and not necessarily monitored by as many WCH users/experts), I also suggest looking at the public Watson Content Hub samples under the git repositories here: https://github.com/ibm-wch including the sample-search-api sample, which may help you understand the WCH Search URLs and search query strings.
    Thanks,
    ..Mike

Join The Discussion

Your email address will not be published. Required fields are marked *