Publish and deliver content

Acoustic Content 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 Content 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 Content delivery system in this tutorial.

Secure content before publishing

The content and website pages that you publish from Content are by default accessible to everyone and do 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 administrator must first set the security in Admin > Settings > Security page.
When the secured content items are published only users that can successfully authenticate to your subscription 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.

Understand options for accessing content through API requests

You can access the content in the Content delivery system in preview mode through the following 4 API access points. All access to the preview API host requires 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://content-XX-N.content-cms.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://content-XX-N.content-cms.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://content-XX-N-preview.content-cms.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://content-XX-N-preview.content-cms.com/api//mydelivery.

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, 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 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 Reference

Publish content on a schedule

You can define specific publishing schedules from the Publishing tab in your Content UI. For more information about the publishing schedule, see Publishing: share your content with the world. When you set a future publish date, Content will put all publish jobs on hold until the next scheduled 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 the HTTP cache expiration step in this tutorial.

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

HTTP cache expiration

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 API calls have a response header that enables a server and client cache expiration of at least 30 seconds. For example, cache-control: public, max-age=30, s-maxage=30.
All published content URL routes for static resource URLs have a response header that enables the following server and client cache expiration.

• Path-based static resources URLs are cached for 1 week.
• Resource ID-based static resources URLs are cached for 24 hrs. Republishing an asset will invalidate the Akamai cache of the asset so that the change is immediately seen.

📘

Note:

Image renditions (images that are transformed) are cached for 24 hours.

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

📘

Note:

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 need 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 Content's default server-side caching.
Akamai caches 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 Content.

Timestamps serve as an ideal value for the unique query parameter field.
https:///api//delivery/v1/search?q=*:*

This request returns all items from 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 --cache. For more information, see the wchtools documentation.

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

For more information, see API Explorer

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 subscription 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 Content, so the binary files loaded from those URLs can be cached forever, 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 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 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
You can get the {API URL} from Developer > URL information page.

• Access assets uploaded through the Content authoring UI
  When you upload assets to your Content by using the Content authoring UI, the asset path values for your files are auto-generated by Content. 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 Content user interface. Open the asset that you want and click the API Information icon on the asset form.

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 a query parameter named assetId. For example, the ID of the asset that is shown in the authoring UI by URL https://content-XX-N.content-cms.com/#/Authoring/Content/My-Assets/cms.jpg?assetId=8b84892a-1cdb-4526-a126-dacd53ac67f7 would be8b84892a-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. You can get the {API URL} from Developer > URL information.
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 a static resource.
https://{DeliveryURL}/{asset-path}
You can obtain the Delivery URL from Developer > URL information. 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 Content user interface. Open the asset that you want and click the API Information icon on the asset form. 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 Content user interface by clicking the API Information icon on the asset form. 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 API URL from Developer > URL information page. 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.

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 Content user interface. Open the content that you want and click the API Information icon on the content form.
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 Content user interface by clicking the API Information icon on 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
You can get the {API URL} from Developer > URL information.

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
You can get the {API URL} from Developer > URL information.

📘

Note:

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

Access static resources

In the 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 Content UI, the following two items are created:

• An asset JSON
  The asset represents the metadata describing the uploaded file, including file name and content type.
  Assets are not immutable. You can change asset metadata or have the asset point to the different resources. 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

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

Resource ID-based resource URLs