Versioning & Upgrade guide
Learn more about our version support policy and the steps you need to take to upgrade your app to a newer API version.
When backwards-incompatible changes are made to the API, we release a new, dated version.
The current version is 2024-05-15
. For information on all API updates, view our upgrade guide below.
By default, requests made to the API use your access token's default API version (you can see that version in the Prepr UI)
unless you override it by setting the Prepr-Version
header.
Support policy
Prepr guarantees technical assistance and security updates for each new version of the GraphQL API for at least 24 months.
Please note that we do not change your API version automatically to avoid breaking your code. Once you are ready to upgrade, please follow the instructions below.
How to upgrade to a newer GraphQL API version
Your API version controls the API behavior you see (for example, how your schema is generated and what fields you can request). When a major or breaking change is introduced to the API, Prepr releases a new version based on the release date. In this case, we encourage our customers to upgrade their GraphQL API versions as soon as possible.
To upgrade to a newer GraphQL API version, you need to generate a new access token for your Prepr environment as follows:
-
Go to Settings > Access tokens and click Add access token.
-
On the New access token details page, provide the name of the token. For example, the access token you use to retrieve all published content items can be titled Published. If you want to preview the unpublished items on your staging site, consider creating an additional Preview token.
-
Next, define permissions for this access token under GraphQL Permissions. Permissions allow you to choose which content item statuses are accessible for an access token. Read more about GraphQL permissions.
-
Click Save to confirm the settings.
Once you've created a new access token, you'll notice the new API version indicated on the Access tokens overview page. By default, the new access token uses the latest GraphQL API version on the token generation date.
Released GraphQL API versions
You can check out the previous Prepr GraphQL API releases below.
version | release date | end-of-life on |
---|---|---|
2024-05-15 | 2024-05-15 | t.b.a |
2024-03-26 | 2024-03-26 | 2026-05-15 |
2024-01-31 | 2024-01-31 | 2026-03-26 |
2023-11-02 | 2023-11-06 | 2026-01-31 |
2023-06-30 | 2023-06-30 | 2025-11-06 |
2023-04-17 | 2023-04-17 | 2025-06-30 |
2023-02-09 | 2023-02-09 | 2025-04-17 |
2023-01-10 | 2023-01-10 | 2025-01-10 |
2022-08-15 | 2022-08-15 | 2024-08-15 |
END OF LIFE | ||
2022-03-20 | 2022-03-20 | 2024-03-20 |
2022-02-15 | 2022-02-15 | 2023-06-01 |
2021-11-29 | 2021-11-29 | 2022-11-29 |
2021-09-27 | 2021-09-27 | 2022-09-27 |
2024-05-15
Version What's new
We are very excited to bring you the long-awaited feature to add fields to Assets. This API release adds support for this new feature. check out the details on the changelog
What's changed
- If an API version is specified by using the HTTP header
Prepr-Version
and set to a non-existing version, this will now generate an exception.
2024-03-26
Version What's new
We are thrilled to introduce the long-awaited Enumerations feature. We've broadened the Schema to allow you to create your own enumerations and use them in any model or component using the List field. The ability to reuse a single enumeration across multiple models and components results in a cleaner Schema.
What's changed
- All list fields are update to use the new Enumerations feature. The response type of all list fields is changed from String or String! to the matching enumeration type.
- All filters on list fields are updated from String to the matching enumeration type.
- Please review your migrated ENUM lists for entries that commence with a numerical character, as ENUM values do not permit starting with an integer.
2024-01-31
Version What's new
- Stack fields are now available in components, making your schema's way more flexible.
- Filtering on content relations is now extended to Stack fields.
- We added new filters for all content reference, remote content and slug fields.
What's changed
- Slug NULL filtering
If null is passed to the _slug_any filter, this release will return all content items without a set slug. The behavior until this version was that all items were returned.
{
Posts(
where: {
_slug_any : null
}
)
}
- Slug ANY filtering
If an empty list is passed to the _slug_any filter, this release will return all content items with a set slug. The behavior until this version was that all items were returned.
{
Posts(
where: {
_slug_any : []
}
)
}
- Content reference filtering
If an empty object is passed to any reference filter, this release will return all content items with at least one referenced item. The behavior until this version was that all items were returned.
{
Posts(
where: {
sections: {}
}
)
}
2023-11-02
Version What's new
Introducing Strict Mode
Strict Mode is released in public beta, if you have any feedback on this new feature, please let us know.
Strict Mode means you get more accurate and reliable TypeScript types from your GraphQL schema.
When you enable Strict Mode, the resulting GraphQL type will be String!
, for example, instead of String
.
When the exclamation mark is omitted then it means the field is a string that will never be null.
In other words, code generators produce the TypeScript type of string
instead of string | null | undefined
.
That means you won't have to handle those additional cases in your front end, and TypeScript won't complain if you
write things like author.name.toLowerCase()
.
Some more
- All model Types now include a new field
_last_published_on
. This field returns the timestamp of the last time the item was published. - Union reference fields can now also be filtered based on the reference
ID
,slug
oftypename
.
What's changed
-
If you enable Strict Mode, all fields in your model and components that are marked as required are now marked as non-null.
-
For all types (except Asset) the
_type
field has been removed, use__typename
instead. -
Collection queries now strictly enforce a pagination limit of 100.
Non-Null Markings
-
For the types FacebookPost, InstagramPost, SoundCloudPost, SpotifyPlaylist, TikTokPost, TwitterPost and VimeoPost the
url
field is now marked as non-null to match the ApplePodcast type. -
For all model types, the event counters are now marked as non-null Integer fields.
-
For the types _DateRange, _DateTimeRange and BusinessHours all fields are now marked as non-null.
-
The BusinessHoursPeriod type fields
open_day
,open_time
,close_day
,close_time
andis_closed
are now marked as non-null.
2023-06-30
Version What's new
- In this release, we've added a new recommendation algorithm to the API. All models now have a People Also Viewed recommendation query.
- An asset field can now be configured as a single-asset field. This removes unnecessary arrays when using an asset field with a single asset.
- The introduction of nested components has made content modeling in Prepr even more powerful. You can now embed one component into another, creating a parent-child relationship within a component.
- For complex filtering, we've added an
OR
filter to the collection filters. - A new
not_contains
filter is available for all Text fields.
What's changed
- Internal links in the text will now remove the
<a
HTML element if the linked content item/asset is deleted or unpublished.
2023-04-17
Version What's new
- Models & Components are extended with a new field
_context
to add more support options for analytics and SSR when using Personalization and A/B testing. - The new
_context
field is added to the Model and Component interface to help keep queries clean. - Stack field now also allows to personalize based on query input of Customer ID or Segment ID's; arguments
personalize_for_country
andpersonalize_for_segments
are added. - Huge speed improvement, especially for customers with complicated content models.
What's changed
- The Component field
_id
will now return the ID of the component instance in a content item instead of the ID of the used component. - On Models the fields
_ab_testing_active
,_ab_testing_version
and_ab_testing_variation
are removed. - The type
PersonalizationAudience
has been renamed toContext
. - The
Content
type has been extended with the new fieldskind
andvariant_id
to simplify implementation. - On Models the
_personalization
field has been renamed to_context
. - On Components the
_audience
field has been renamed to_context
.
2023-02-09
Version What's new
-
Introducing a new field type Stack; This new field makes it much easier to structure and compose your component-based web pages. When you add this field in your content models, you can add other items and components in a single step when composing the content.
-
All Models and Components now reference to their specific Interface Types. This will make some queries much shorter since the overlapping default fields can now be queried together.
-
On the all types query
ContentItems
we added the_slug_any
filter to make it easier to find pages without knowing the type. -
We added new API permissions, with more fine-grained control on the access level of content items.
-
It is now also possible to switch off schema introspection on the access token settings page
What's changed
-
The asset field
Url
returns now by default a optimized url for images instead of the original uploaded file. -
The asset field argument
player
has been removed from theUrl
field. -
The
personalized_
queries are removed, use the new Stack fields instead. -
The Component field
_id
is now marked as non-null. -
The argument
locale
on the singular and collection queries is now marked as non-null. -
We removed support for the beta version for Personalization (this affect all previous versions of the API).
How to Update
In most cases this update doesn't require action from your side. Please review the changes mentioned above carefully.
2023-01-10
Version What's new
-
Introducing new Type Remote source.
-
Filter collections on the Business Hour field types.
-
Added new filters for Integer, Float, Date, DateTime and Date Range fields.
-
Added popular sort for ContentItems query (multi type filtering).
-
Improved error description when using an expired access token.
-
Security and speed optimizations.
What's changed
- Content integration support is removed, please update your integration to the new Remote source type.
- Types
ContentIntegration
,ContentIntegrations
,KeyValue
andNumber
are removed.
How to Update
For Remote Source fields in a content model or component the query changes as follows:
Before 2023-01-10
:
{
Product( id : "7e34880a-bbc7-4b6a-9642-c29c6d91a694" ) {
commercelayer { // Content Integration field
_id
data {
key
value
}
}
}
}
Fields can now be specified in the Remote Source.
{
Product( id : "7e34880a-bbc7-4b6a-9642-c29c6d91a694" ) {
commercelayer { // Remote Content field
_id
product_id
name
....
}
}
}
Remote content fields in a dynamic content editor field are also updated, check out the details on the Dynamic content field page.
2022-08-15
Version What's new
-
With the introduction of the
_localization
field you are able to fetch all locales of a content item in just one query. Making it easier to create language switches in your apps. -
For A/B testing we added the
_ab_testing_variation
field. This field returns the variant version of a content item if there is an active A/B test. -
Extended the native support for Mux video adding all cover formatting options and the new
playback_id
field. -
More speed improvements.
What's changed
-
Content models: The fields
_locale
,_localization
and_locales
are now only being added to your content model if localization is active in your Prepr environment. -
Content models: The fields
__ab_testing_active
,__ab_testing_version
are now only being added to your content model if A/B testing is activated for that model. -
Content models: The field
__ab_testing_active
field now returns true if there is an active A/B test on that content item. -
Components: Reference fields now have their own
Union types
if referencing multiple content models. -
Components: The
_type
field is removed for components, use__typename
instead. -
Asset:
_id
is now marked as Non-Nullable field. -
Asset:
playback_id
is added to easy implementation of the new Mux Player. -
Asset: the field
cdn_files
is removed for customers using Mux.
2022-03-22
Version This is a minor release, the url
field on image assets will now return the full
image instead of a default cropped size if no size is specified.
If you want to keep a default crop, just specify the default cropped size (width:1920)
in the query:
{
Recipe( locales : ["en-US", "fr-FR", "nl-NL"], id : "7e34880a-bbc7-4b6a-9642-c29c6d91a694" ) {
image {
url(width:1920)
}
}
}
2022-02-15
Version Where & Sort Inputs
The Input types for Where filters and Sort filters are now using the singular name instead of the plural name of a content model. Queries need to be updated to reflect the new type name.
For example:
query ExampleQuery($where: RecipeWhereInput) {
Recipes(where: $where) {
items {
title
}
}
}
Query before 2022-02-15
:
query ExampleQuery($where: RecipesWhereInput) {
Recipes(where: $where) {
items {
title
}
}
}
Personalization, Similarity and Popularity
The queries Personalized_
, Similar_
and Popular_
collections now use the plural name of a content model.
New query:
Personalized_Recipes {
items {
title
}
}
Query before 2022-02-15
:
Personalized_Recipe {
items {
title
}
}
_model
field
Removed In this version we removed the field _model
to identify a content item. You should use __typename
instead.
Publications
renamed to ContentItems
To match the terminology used in Prepr the query Publications
is renamed to ContentItems
.
2021-11-29
Version In this version we changed the default formatting of heading elements inside a Dynamic Content field.
They now include HTML <hX></hX>
tags by default. If you need the plain text, change the field in your query from body
to text
.
New formatted response:
{
"data": {
"Page": {
"dynamic_field": [
{
"body": "<h1>Hi1</h1>"
}
]
}
}
}
Response in version 2021-09-27
:
{
"data": {
"Recipe": {
"dynamic": [
{
"body": "Hi1"
},
{
"body": "H2"
}
]
}
}
}