Overview

Skill Level: Any

IBM Watson Content Hub provides a delivery system that is optimized for highly efficient delivery of content to clients by using the Akamai Content Delivery Network (CDN) infrastructure. The content that is created on the authoring system is made available on the delivery system by the publishing process. The publishing process copies and transforms the content and assets that are uploaded through the Watson Content Hub User interfaces to the Akamai CDN. As a result, your published content automatically gets replicated on the worldwide Akamai content delivery infrastructure to edge servers close to the users. Learn how to work with the Watson Content Hub Delivery system in this tutorial.

Step-by-step

  1. Secure content before publishing

    The content and website pages that you publish from Acoustic Content are by default accessible to everyone and does not require authentication. You can secure and restrict access to selected content and website pages before you publish.

    To secure and restrict who can access the secured content, your hub administrator must first set the security in the security tab of your hub’s general settings.

    When the secured content items are published only users that can successfully authenticate to your hub can access them. This restriction also applies to all API entry points that directly or indirectly serve the published content or pages, such as the delivery content service, the delivery site service, the delivery render service, and the delivery search service.

  2. Understand options for accessing content through API requests

    You can access the content in the Acoustic Content delivery system in preview mode through the following 4 API access points. All access to the preview API host requires Acoustic Content authentication.

    You can access your public live data by using the /delivery/* routes. These routes do not require authentication and will never serve content that is secure. You can access all your live data, including the secure content that was flagged to require authentication, by using the corresponding /mydelivery/* routes. These routes do require authentication

    1. Access Public Live Content — Public Live Content is published content that is accessible to your clients without any authentication. You can access the Public Live Content by using the URL format
       https://myXX.digitalexperience.ibm.com/api/<tenant-id>/delivery
    2. Access Protected Live content — Protected live content is all published content including content that requires authentication. You can access the Protected Live Content by using the URL format
       https://myXX.digitalexperience.ibm.com/api/<tenant-id>/mydelivery
    3. Access Draft Content — Draft content is unpublished content that is not accessible to your clients. You can preview your unpublished content updates that are made to the Public live content by using the URL format
      https://myXX-preview.digitalexperience.ibm.com/api/<tenant-id>/delivery
    4. Access Protected draft content — Protected draft content requires authentication. You can preview your unpublished draft content that is protected by using the URL format
       https://myXX-preview.digitalexperience.ibm.com/api//mydelivery
  3. Publish content

    The publishing process is performed by publishing jobs. A publishing job handles all updates that are made to your content that is in the ready status since the last successful publishing run. Whenever your content authors update the content to the Publish status, Acoustic Content automatically triggers a corresponding publishing job underneath the covers to transfer the corresponding updates to your delivery site. You can turn off this automatic publishing feature on your tenant by using the Publishing APIs. When you turn off the automatic publishing, all publish jobs are put on hold until you explicitly trigger the publish operation by using the wchtools command-line interface or the Publishing APIs. For more information about wchtools and Publishing API, see wchtools-cli and API documentation.

    Publish content on a schedule

    You can define specific publishing schedules from the Publishing tab in your Acoustic Content UI. For more information about publishing schedule, see Publishing: share your content with the world. When you set a future publish date, Acoustic Content will put all publish jobs on hold until the next schedule event. If you want to trigger a publishing operation before the next scheduled publish event, you can do so by using the wchtools command line interface or the Publishing APIs.

    The availability of content on the delivery site depends on the system load and the size of your content modifications. For example, depending on the size of the video file that is uploaded in the authoring system, there may be a delay of when the new or updated content is available on your delivery site. For more information, see HTTP cache expiration step in this tutorial.

  4. Understand content transformations after publishing

    The published versions of your content items are transformed into a delivery format that is optimized for use in client applications. The following transformations are made:

    • Asset URL generation

      An url property is added to the JSON objects that represent references to assets of type video or file. The value of this property is a server relative URL that directly addresses the published version of the referenced image or file asset.

    • Image rendition URL generation

      An url property is added to the JSON objects that represent references to image renditions. The value of this property is a server relative URL that directly addresses the published version of the referenced image or image rendition.

    • Image transformation parameters

      When addressing images, you can add the following query parameters to transform the addressed image prior to serving.

      • resize – Example: ?resize=120px:120px
      • downsize – Example: ?downsize=640px:*
      • crop – Example: ?crop=200px:100px;20,10
      • output-quality – Example: ?output-quality=50
  5. HTTP cache expiration

    Acoustic Content implements a system-wide level of caching that improves the average response times for all requests to access the public live content.

    All published content URL routes for both API calls and static resource URLs have a response header that enables a server and client cache expiration of atleast 10 seconds. For example, cache-control: public, max-age=10, s-maxage=10.

    The draft content and protected live content require authentication and is not cached publicly on the edge server.

    Note: Acoustic Content performs an additional ETag / validation based caching independent of the expiration times.

    Based on this caching process, you might need to consider how often your backend data will be updated and how quickly you want that change to be reflected in your application. For example, if you are displaying a list of search results that needs to be updated frequently, you might want to consider disabling this caching through the query parameters you send with your request.

    Bypass server-side caching

    If you want to ensure that your application has the latest results with every API call, you can bypass Acoustic Content’s default server-side caching.
    Akamai caches Acoustic Content results based on the full URL of the request.
    For example, in the Search API, since the full URL is cached, the addition of a unique query parameter guarantees a cache miss and pulls the data directly from Acoustic Content.
    Time stamps serve as an ideal value for the unique query parameter field.

    https:///api//delivery/v1/search?q=*:* 

    This request returns all items from Acoustic Content.

    https:///api//delivery/v1/search?q=*:*&uniqueQueryParam=<unique value>
    https:///api//delivery/v1/search?q=*:*&timestamp=1551716331480

    You can also use the wchtools to invalidate the edge cache with the following command wchtools clear --cac.
    For more information, see the wchtools documentation.

  6. Access protected published content and pages

    All delivery services that support secured published data offer dedicated API routes for accessing the secured data. All those routes use the common /mydelivery base context as opposed to the /delivery context that serves the public (unprotected) content.

    All /mydelivery APIs require a valid hub security context. You must first log in before you can call these APIs. Otherwise, the requests are rejected. The /delivery routes serve only the non-restricted data even when called with a valid hub security context (to maintain cachability). Detailed information on those API routes can be found in the API documentation.

    The following table shows the delivery services available and the methods to access all published content and content that is secure through these services.

    Delivery service Accessing all published content Accessing secure content
    Search for content, assets, types /delivery/v1/search /mydelivery/v1/search
    Access individual content items /delivery/v1/content /mydelivery/v1/content
    Access binary asset data /delivery/v1/resources N/A
    Access your sites and pages /delivery/v1/site /mydelivery/v1/sites
    Access JSON rendering context for pages/sites /delivery/v1/rendering /mydelivery/v1/rendering
    For more information, see API Explorer

  7. Access published assets

    The published versions of your assets can be accessed from your delivery system through the following two entry points:

    • Asset path

      Accessing the published asset through the asset path addresses your published resource as public static resource. The published asset is directly retrieved from the replicated storage infrastructure that is provided by Akamai. This entry point provides the best performance for accessing your published assets.

      Note: The path-based URLs work only after your tenant is activated with Akamai. You might not be to access the assets through the asset path immediately as it takes some time for the Akamai activation.

    • Resource ID

      Accessing the published assets through the resource ID identifies a specific asset binary. This access point is provided by the delivery resource service API. You can find the corresponding API documentation in the Acoustic Content API documentation.

      Note: Accessing the resource service API does not require authentication.

    Resources by themselves are immutable in Acoustic Content, so the binary files loaded from those URLs can be cached for ever, but they are not retrieved directly from the Akamai storage infrastructure. Use the delivery resource service API if you want to directly address a specific asset binary independent of the asset path. You can build the delivery URLs to access your assets by completing the steps that are provided in the following sections.

    Access published assets by their path

    You can access published assets by their path based on how they were uploaded:

    • Access assets uploaded through wchtools

      When you upload assets to your Acoustic Content by using the wchtools command line interface, the asset path values for your files match the file paths from your local file system.

      For example, if you have a file /tmp/wch/assets/images/test.png that you push into Acoustic Content through wchtools push --dir /tmp/wch
      the resulting asset has an asset path value of images/test.png. You can access this file as a static resource by using the following URL pattern:

      https://{API URL}/ images/test.png

      where the API URL is constructed as Domain name/{path} where {path}= api/{Content hub ID}. You can construct the API URL by getting the Domain name and the Content hub ID from the Authoring UI or you can get the {API URL} from the WCH Authoring UI Ribbon> About> Hub information. A pop-up window displays the Domain name and the Content hub ID.

    • Access assets uploaded through the Acoustic Content Authoring UI

      When you upload assets to your Acoustic Content by using the Acoustic Content Authoring UI, the asset path values for your files are auto-generated by Acoustic Content. Acoustic Content constructs the individual asset path values by adding a unique path prefix to the name of your uploaded file. The prefix is added to avoid name collisions when you upload multiple files with the same name. You can obtain the ID for the asset from the Acoustic Content user interface. Open the asset that you want and click the API Information icon below the asset.

      You can also determine the asset path value by completing the following steps:

      1. Click the asset to open the asset details view.
      2. Obtain the asset ID from the browser URL. The browser URL contains the asset ID as query parameter named assetId. For example, the ID of the asset that is shown in the Authoring UI by URL https://www.digitalexperience.ibm.com/#/Authoring/Content/My-Assets/ibm.jpg?assetId=8b84892a-1cdb-4526-a126-dacd53ac67f7 would be 8b84892a-1cdb-4526-a126-dacd53ac67f7
      3. Load the asset metadata by using the Authoring asset service (API Explorer).

        Note: You must be authenticated to use the Authoring asset service APIs. If you are timed out or did not authenticate, an error is returned.

        When you provide the asset metadata in the authoring asset service, the corresponding URL would look like

         https://{API URL}/authoring/v1/assets/8b84892a-1cdb-4526-a126-dacd53ac67f7

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

        You can construct the API URL by getting the Domain name and the Content hub ID or the {API URL} from the Acoustic Content Authoring UI Ribbon> About> Hub information. A pop-up window displays the Domain name and the Content hub ID.

      4. Find the path property with the asset path value in the JSON record that is returned by this URL.
      5. Provide the asset path value from the JSON record in the following URL pattern to access the asset file as static resource.
         https://{Domain name}/{Content hub ID}/{asset-path}

        Replace {Domain name} with your tenant Domain name and {Content hub ID} with your Content hub ID.

        You can obtain your tenant Domain name and your Content hub ID values from Acoustic Content Authoring UI Ribbon> About> Hub information. A pop-up window displays the Domain name and the Content hub ID.

        Replace {asset-path} with the asset path value that you retrieved in the previous step.

    • Support for relative URLs

      Relative URLs are supported when addressing published assets as static resources by using the path- based URLs. The Delivery resource service API allows addressing resources through a path URL query parameter. This API does not support relative URLs. More information on the Delivery resource REST API, can be found here: API Explorer.

    Access assets by their resource ID

    You can obtain the ID for an asset from the Acoustic Content user interface. Open the asset that you want and click the API Information icon below the asset. You can also obtain the ID of the resource for an asset from the asset JSON records. The JSON record contains the resource property with the ID of the asset. You can access the API information that is needed to get the JSON record from the Acoustic Content user interface by clicking the API Information icon below the asset. You can also get the ID from the JSON returned by the Authoring Asset service or the results of the Authoring Search service. Follow the steps that are provided in Accessing assets by their path to retrieve the JSON record for an asset.

    Note: You must be authenticated to use the Authoring asset service APIs. If you are timed out or did not authenticate, an error is returned.

    Provide the resource ID from the JSON record in the following URL pattern to access the resource that is associated to a published asset https://{API URL}/delivery/v1/resources/{resource-id} and replace {API URL} with your tenant API URL from the Acoustic Content Authoring UI Ribbon> About> Hub information. A pop-up window displays the API URL. Replace resource-id with the resource ID that you retrieved from the JSON record.

    More information on this API can be found here: API Explorer.

  8. Access published content

    The content items in the ready status are published to the delivery system. Content items in the draft status are not published until they are moved to ready status.

    Note: Changing the status of a published content item to the retired status does not unpublish it. To unpublish a content item, you must delete it.

    You can access the published version of content items by providing the content Item ID in the Delivery content service API. You can find the corresponding API documentation in the Acoustic Content API documentation.

    You can obtain the Item ID from the Acoustic Content user interface. Open the content that you want and click the API Information icon below the content.

    The publishing process does not modify the content Item ID. Therefore, you can also use the Item ID value that is retrieved from the content item JSON on the authoring service to access the published version of that content item. You can access the API information from the Acoustic Content user interface by clicking the API Information icon from the Information tab of the content form.

    For example, assume that you created a content item on the authoring service with the following ID

    xxxxxxxx.xxxx.xxxx.xxxxxxxxxxxx

    You can access the authoring version of this content item by using the following URL pattern:

    https://{API URL}/authoring/v1/content/xxxxxxxx.xxxx.xxxx.xxxxxxxxxxxx

    where the API URL is constructed as Domain name/{path} where {path}= api/{Content hub ID}. You can construct the API URL by getting the Domain name and the Content hub ID from the Authoring UI or you can get the {API URL} from the Acoustic Content Authoring UI Ribbon> About> Hub information. A pop-up window displays the API URL.

    You can access the published version of this content item by using the following URL pattern:

    https://{API URL}/delivery/v1/content/xxxxxxxx.xxxx.xxxx.xxxxxxxxxxxx

    where the API URL is constructed as Domain name/{path} where {path}= api/{Content hub ID}. You can construct the API URL by getting the Domain name and the Content hub ID from the Authoring UI or you can get the {API URL} from the Acoustic Content Authoring UI Ribbon> About> Hub information. A pop-up window displays the API URL. You can use the exact same URL but by replacing the authoring path segment with delivery you can access the published content.

    Note: Authentication is not required to access the published version of your content.

  9. Access static resources

    In the Acoustic Content Static Resource model, the Asset is a resource metadata {JSON} and the File is an actual binary {image, script).

    When you upload a static resource such as a jpg, js, mp4 in the Acoustic Content UI, the following two items are created:

    • An asset JSON

      The asset represents the metadata describing the uploaded file, including: file name, content type.

      Assets are not immutable. You can change asset metadata or have the asset point to the different resource
      The latter is actually happening when you modify the image in an image asset. For example, using the Shutterstock image editor.

    • The resource binary

      For example, the actual jpg file.

      Resources are considered immutable, which means you cannot modify a resource after it is uploaded. The only thing that you can do is upload a new resource with a new resource ID.

    URLs to access static resources

    Acoustic Content supports the following URLs to address a static resource:

      • Asset path-based Resource URLs

        The URL always points to the resource that is assigned to the addressed asset. For example, when you update the asset to point to a different resource, the URL changes to point to the new resource. As a result, the addressed resource (the asset) is not immutable and the URLs can get stale if cached on the client.

        Path-based addressing is a prerequisite for using relative paths (for example, in HTML or JS). Path-based URLs typically more readable, which can improve SEO ranking

      • Resource ID-based Resource URLs

        The addressed resource is immutable and the URL can be cached for long.

    Asset Path based resource Urls

    URLs Structure Examples Default cache max-age
    Resource base URL <resources-base-url>/<asset-path>

    https://my1.digitalexperience.ibm.com/552fd080-e4c6-4aca-9f5b-b2d618c0d617/dxdam/62/62ed6da5-6921-45bb-96b8-a75d7bbdc120/GutenbergLogo.jpg

    https://uwe.wchtest.xyz/dxdam/62/62ed6da5-6921-45bb-96b8-a75d7bbdc120/GutenbergLogo.jpg

    11 minutes
    API based <api-base-url>/delivery/v1/resources?path=<asset-path>

    https://my1.digitalexperience.ibm.com/api/552fd080-e4c6-4aca-9f5b-b2d618c0d617/delivery/v1/resources?path=/dxdam/62/62ed6da5-6921-45bb-96b8-a75d7bbdc120/GutenbergLogo.jpg

    https://uwe.wchtest.xyz/api/delivery/v1/resources?path=/dxdam/62/62ed6da5-6921-45bb-96b8-a75d7bbdc120/GutenbergLogo.jpg

    10 seconds

    Resource ID-based resource Urls

    URLs Structure Examples Default cache max-age
    Resource based <resources-base-url>/dxresources/<resource-id-prefix>/<resource-id><file-suffix>

    This URL format cannot be constructed by clients. It is only used as generated URLs for in asset elements.

    11 minutes

    API based

    Resource ID for an asset can be obtained through delivery search with the field &fl=resource.

    <api-base-url>/delivery/v1/resources/<resource-id>

    https://my1.digitalexperience.ibm.com/api/552fd080-e4c6-4aca-9f5b-b2d618c0d617/delivery/v1/resources/4NIX12-olxmiXoBRjvNq0eYvTC9xu22m9qjOcfAN08I

    https://uwe.wchtest.xyz/api/delivery/v1/resources/4NIX12-olxmiXoBRjvNq0eYvTC9xu22m9qjOcfAN08I

    24 hours

Join The Discussion

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