Introduction
The Delivery API 1.0 provides REST endpoints for SPAs to retrieve JSON representations of:
- A list of available channels
- Pages in a channel, including all the components, content items, and menus of which those pages are comprised
- A specific document in the context of a channel
Following the core principles of HATEOAS, the SPA enters the REST application through a Bloomreach Content navigational URL and discovers all possible future client interactions within the resource representations returned from the server.
Additionally, the Delivery API 1.0 provides seamless integration with the channel preview and page management features of the Experience manager application. This API now also includes an optional ability to share unpublished content with users and systems outside the Bloomreach Content GUI, using a feature we call External preview.
The Delivery API 1.0 is primarily designed to be used in combination with the Bloomreach SPA SDKs.
The Delivery API 2.0 is more generic than the Delivery API 1.0 and provides the basic building blocks to support a multitude of use cases, such as fetching individual content items, mobile app development, and site development without using the SDK.
Prerequisites
For the Delivery API 1.0 to work as desired, make sure that:
- you have at least a 'home' Experience page and
- your 'home' page is published.
Not meeting these requirements will result in a 404 Error.
API base URL
https://<environment_name>.bloomreach.io/delivery/site/v1/
Authentication
When accessing the Delivery API 1.0 through a live endpoint, by default, it will return a channel's published pages and content. This requires no authentication.
In order to access unpublished pages and content and render the channel preview in the Experience manager app, an external frontend application must authenticate using a JSON Web Token. This is normally handled automatically by the Bloomreach SPA SDK.
For External preview, users prove their right to access unpublished content for a specific project by authenticating with an anonymous UUID associated with the project rather than using the JWT-based handshake. This feature must be enabled on each project for which it will be used.
Configuration
The Delivery API 1.0 can be configured using the Delivery API Settings Management API. Configuration options include enabling and disabling the API, and whether to include translations in the responses.
API status and versions
You can check the health status and available versions of the API at the following URL:
https://<environment_name>.bloomreach.io/delivery/site/
If the Delivery API 1.0 is available, you'll receive a 200 response with a body like the following example:
{
"status" : 200,
"message" : "OK",
"apiVersions" : [ "v1" ]
}
Please note that as of release 20220519, the health check returns status 200 even if there are no channels defined. In earlier releases, this situation resulted in a 404 response.
CORS and Preflighted Requests
If your frontend application makes preflighted request to the Delivery API 1.0 endpoints, you may run into CORS errors. A preflighted request is typically the result of adding request headers to the request (for example,Content-Type: application/json).
To prevent this, configure the Access-Control-Allow-Headers header in your channel's responseHeaders configuration property using the Site Management API's Channel endpoint or using the Site development app.
Make sure that all the request headers specified in your preflighted requests are present in the Access-Control-Allow-Headers response header (for example Access-Control-Allow-Headers: Content-Type).