Content Hub includes a RESTful API 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 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.
For information about the other APIs available to Personalization subscribers, see Using the Personalization APIs.
Using the REST API
Like 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:
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, Acquia encourages you to use the ping call to test your connection to the API. To do this, complete the following steps:
Open a command prompt window, and then enter the following command:
curl -XGET "http://[example.com]/ping"replacing
[example.com]with the Content Hub API URL provided by your Acquia technical contact.Ensure 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:
Create a
composer.jsonfile in the root of your project:{ "repositories": [ { "type": "vcs", "url": "https://github.com/acquia/content-hub-php" } ], "require": { "acquia/content-hub-php": "*" } }Install the package. The following command can be used for installation:
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, a Drupal application should use HMAC to check the authenticity of the request to ensure it comes from the same Content Hub server the application communicates with. This prevents malicious servers sending requests to the application and modifying data. To check the request, Content Hub and each application registered on Content Hub share a secret key used to check 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 must contact Content Hub to request the shared secret, and store this in a variable for future use.
Note
Content Hub relies on HTTPS to encrypt data. To ensure the security of your data, Acquia recommends using HTTPS on your Drupal website.
You can use the Content Hub Client for PHP to register with Content Hub and authenticate your API calls.
Registering with Acquia 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 configure the Acquia Content Hub Connector.
To register with Content Hub, use the register API call. Before 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 you must use in your later 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 it works.
Here is some example code using 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’re registered, you can use this as your client ID, which shouldn’t 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. You can’t 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/:
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 Profiles API reference.
Besides 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. You can obtain keys having only limited permissions if, for example, you have users who must create content, but you don’t want them to delete content. If you need API keys with customized permissions, create a Support ticket.
The available permissions are as follows:
- administer
- create
- search
- register
- update
- delete
- retrieve