What is a Preview API?
It’s a bit hard to preview content when you’re decoupled from your frontend, right? Enter the Preview API...
A Preview API is a crucial feature of a headless CMS which allows you to configure your own Preview mode, and make life much easier for your editors.
Technically, the Preview API is 1:1 with the Content Delivery API, which means that it can be swapped out whenever something needs to be previewed.
Both of our client libraries also allow you to switch between the two APIs, so you can use it from within your website, application or whatever else you are building.
Who benefits from the Preview API?
In a traditional CMS - where the backoffice and website live together within the same application - you can see your changes on the website before publishing with a click of the Preview button. This is super handy for content editors, who can double-check their changes before they are shipped to the world.
But in the context of a headless CMS, the frontend or presentation layer can be anything from a website to a mobile app, to an app running on a refrigerator, so we need to look at it differently. How do we make sure that content editors can still preview their content? That’s where Preview API comes in.
Now, given that almost everything in a headless context is based around APIs, it makes sense to utilize an API to preview on both websites and apps.
As a developer, you can now utilize the Preview API in Umbraco Heartcore to enable previewing capabilities in what you are building in order to give the content editors the option to Preview their changes before they are published.
What can you do with a Preview API?
In Umbraco Heartcore there are two sides to the Preview story:
- The configuration of the Preview button in the Umbraco Backoffice
- The Preview API available via preview.umbraco.io
Configuring the Preview button in the Umbraco Backoffice
From within the Settings section of the backoffice you will find the Preview feature, which enables you to define the Preview options that you want to make available to the Content Editors.
In order to set up the preview options for your content editors you need to add preview urls through the Headless tree in the Settings Section. Let's take a look at that now...
- First off, you select the root node for which you want to enable this Preview option.
- Then, you select the culture and enter the URL that you want the Preview button to open.
- This URL can be anything openable from the browser and is where you, as a developer, have made the website or app available and ready to Preview using the Preview API.
- Optionally, you can customize how to structure the URL or Querystring to the content preview, making for ultimate developer flexibility 😉
Once the Preview URL has been created you will get a Preview button on all content, which takes you to the configured URL. And the beauty of all of this is that you can create multiple URLs for the same content and choose which one should be the default.
A configured preview button
That means you can add the option that suits your needs.
Read more on the Preview documentation
Configure the API on preview.umbraco.io
To get the Preview to actually work, you (as a developer) will need to incorporate it into your website or app, and create the destination where the Preview button takes you.
Whether you choose to have the Live instance work with Preview mode or create another instance specifically for previews is entirely up to you.
An API Key is required on all requests going to preview.umbraco.io, as the Preview API is protected by default.
The endpoints and responses from the Preview API are the same as those of the Content Delivery API, so it's easy to switch between the two. If you are using the .NET Core or NodeJs client libraries, then we’ve made it easy for you to switch between using the API for published content (the Content Delivery API) and for draft content (the Preview API).
Whenever content is saved, it's available through the Preview API, so you always get the latest draft.
Check out the API documentation
So, what’s so great about Preview API?
It’s flexible
With the Preview API, you get full control over how you want to preview your content; live or not live? URL or configured API? Whatever suits you.
It's "environmentally friendly"
You can use the Preview API in any environment. Let’s say for example, you could use the staging environment as a dedicated preview environment for content editors, which are then published when transferred to Live. As developers, you have full creative freedom.
It’s in your own coding language
Since the Preview API is directly linked to the backoffice, it can be used in any coding language - including the client libraries. Keep using the coding language you're used to.
It’s simple, but important.
It’s important for editors to be able to preview their content before publishing; testing live is risky, and frankly unnecessary. The Preview API is a crucial part of a headless cms, so you can rest assured that you have all of the functionality you need to create your innovative headless solutions.
How do I try out the Preview API?
With a free 14-day trial of Umbraco Heartcore, you can discover the preview possibilities and figure out what works for you!