Using the Content Hub API

Content Hub includes a RESTful API that you can use to create, read, update, and delete content.

Using the API, you can source content from anywhere and then connect and use that content with your many websites, native mobile applications, or other digital experiences — all while maintaining data integrity and security. You can use the API to also build custom applications that publish, update, and consume content, and then render that content natively.

Using the REST API

Similar to many other APIs, the Content Hub API uses standard HTTP methods to communicate with the service, including GET, PUT, POST, and DELETE. You can view the list of available Content Hub API calls at the following URL:

http://api.content-hub.acquia.com/

Sample Content Hub API methods

Here are some examples of the methods provided in the Content Hub API:

REST API call Description
ping Determine if the API is responding
entities Stores a piece of content, prepared for synchronization
settings Retrieve subscription configuration
register Register a new client
webhooks Manipulate subscription webhooks

For complete documentation, see the Content Hub API Reference.

Testing your connection

When you first start using the Content Hub API, we encourage you to use the ping call to test your connection to the API. To do this, complete the following steps:

  1. Open a command prompt, and then enter the following command:

    curl -XGET "http://[ch_api_url]/ping"

    where [ch_api_url] is the Content Hub API URL provided by your Acquia technical contact.

  2. Verify that the API call returns the following results:

    {
      "success": true
    }

Using the Content Hub client libraries

Content Hub also includes a PHP SDK, the Content Hub Client for PHP, which you can download.

Content Hub Client for PHP can be installed with Composer by adding it as a dependency to your project's composer.json file. To do this, complete the following steps:

  1. Create a composer.json file in the root of your project:

    {
        "repositories": [
            {
                "type": "vcs",
                "url": "https://github.com/acquia/content-hub-php"
            }
        ],
        "require": {
            "acquia/content-hub-php": "*"
        }
    }
  2. Install the package. The following command can be used to do this:

    composer install

Authenticating API calls

Content Hub API calls are authenticated using HMAC, a shared-secret cryptography method where signatures are generated on the client side and validated by the server to authenticate the request.

When receiving a webhook request from Content Hub, an application like Drupal should use HMAC to verify the authenticity of the request in order to ensure it comes from the same Content Hub server that the application normally communicates with. This prevents malicious servers sending requests to the application and modifying data. To verify the request, Content Hub and each application that is registered on Content Hub share a secret key, which is used to verify the signature of any incoming web request (or webhook). When an application registers and receives a webhook for the first time, the shared secret will be missing. In this situation, the application should immediately contact Content Hub to request the shared secret, and store this in a variable for future use.

You can use the Content Hub client for PHP to register with Content Hub and authenticate your API calls.

Registering with Content Hub

Before using any API calls, you must register with Content Hub, or you will receive an error message in response.

Registering with Content Hub requires the following items:

  • Content Hub API key - Provided by your Acquia technical contact
  • Content Hub Secret key - Provided by your Acquia technical contact
  • Content Hub website name - Set by you when you configured the Acquia Content Hub Connector

To register with Content Hub, use the register API call. Prior to registration, the origin can be set to any value. When you register for the first time, you will receive a paired origin UUID and client name that you must use in your subsequent requests (any other API call).

After your client is registered, all other API calls are open to you using that registered origin. You can test registration by doing any query to any other API function (and using your origin in the requests) and ensuring that it works.

Here is some example code that uses the Content Hub Client for PHP:

$api = 'AAAAAAAAAAAAAAAAAAAA';
$secret = 'BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB';
$origin = '11111111-0000-0000-0000-000000000000';

$client = new ContentHub($api, $secret, $origin, ['base_url' => 'http://localhost:5000']);

// Register a client
$client_site = $client->register('myclientsite');

The register call returns a UUID that you use as the origin in the following requests:

$origin = $client_site['uuid'];
$client = new ContentHub($api, $secret, $origin, ['base_url' => 'http://localhost:5000']);

After you are registered, you can use this as your client ID, which should not expire. If you use other methods of registration (such as getClientByName()), these may expire, and cause unexpected errors.

When you have a registered origin, the getClientByName() call can be used to obtain both the site name and site origin pair of a specific registered website. However, you cannot use that API call to register a website. For example, if you already registered a website and execute getClientByName(), you are essentially requesting Content Hub /settings/clients/<name>:

HTTP REQUEST "/settings/clients/centralstation" [Using a registered ORIGIN UUID]

Array
(
    [name] => centralstation
    [uuid] => 1231212-1234-1234-1b2e-3a567dfa8d90
)

API keys and permissions

Content Hub API commands require authentication using both an API key and a secret key. For information about how to review your Content Hub keys, see Acquia Lift REST API reference.

In addition to your originally provisioned keys, commands may require particular permissions for an API key. By default, all API keys have every permission for each method in the Content Hub API. However, you can obtain keys that have only limited permissions if, for example, you have users who need to be able to create content, but you do not want them to be able to delete it. If you need API keys with customized permissions, contact your Acquia technical advisor.

The available permissions are as follows:

  • administer
  • create
  • search
  • register
  • update
  • delete
  • retrieve

Add new comment

Plain text

  • No HTML tags allowed.
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.

Contact supportStill need assistance? Contact Acquia Support