Storyblok Content Delivery API V1 vs V2: The Differences

This FAQ highlights crucial differences between Storyblok Content Delivery API V1 and Content Delivery API V2. Understanding these differences is essential for a seamless transition to the enhanced features and improved performance of Content Delivery API V2.

Potential Conflicts with Folder Names in Content Delivery API V1

In Content Delivery API V2, improvements have been made to optimize internationalization, specifically regarding how field-level translations are handled. Unlike Content Delivery API V1, where language versions are requested via the slug, Content Delivery API V2 uses a dedicated language parameter.

See the examples below:

Content Delivery API V1 Example Request:

        
      GET https://api.storyblok.com/v1/cdn/stories/fr/home?token=YOUR_ACCESS_TOKEN
    

In Content Delivery API V1, direct slug usage for language versions can lead to potential conflicts with folders that share names with language codes (e.g., fr, de, en).

For instance, having a folder named fr might create ambiguity when accessing the French version of a story.

Content Delivery API V2 Example Request:

        
      GET https://api.storyblok.com/v2/cdn/stories/home?language=fr&token=YOUR_ACCESS_TOKEN
    

Improved Cache Invalidation System

Content Delivery API V2 features a more robust cache invalidation system, ensuring content updates are reflected accurately and promptly. For a high cache hit rate for published content, the Content Delivery API V2 appends a parameter called cv, representing the cache version. The stories endpoint provides the cv parameter in the Content Delivery API.

Below is an example object with a cv value.

        
      {
  "story": {
    "name": "Example",
    "slug": "example",
      ...
  },
  "cv": 1541863983
}
    

Read more about the improved cache invalidation and how to optimize your caching strategy in Content Delivery API V2.

Validation of API Parameters

The parameters used in the stories endpoints are now validated in Content Delivery API V2. If disallowed parameters are detected during a request to the Content Delivery API, an HTTP status code 422 with a clear error message is returned.

Here's an example of a request for receiving stories with an incorrect start_with parameter.

        
      GET https://api.storyblok.com/v2/stories?start_with=products&per_page=10&token=ACCESS_TOKEN
    

Response:

        
      {
  "error": "Parameter(s) start_with not allowed"
}
    

Since the start_with parameter is incorrect, the error message is returned when the Content Delivery API V2. The correct API parameter to use would be starts_with .

Changes in Response

In Content Delivery API V2, substantial updates have been made to the JSON response format, introducing new fields and more information.

Content Delivery API V1

The JSON response format in Content Delivery API V1 is represented below:

        
      {
   "story": {
      "name": "An example story",
      "created_at": "2024-01-16T08:54:33.576Z",
      "published_at": "2024-01-29T16:52:53.476Z",
      ...
   }
}
    

Content Delivery API V2

The JSON response format in Content Delivery API V2 has been updated with more fields.

        
      {
   "story": {
      "name": "An example story",
      "created_at": "2024-01-16T08:54:33.576Z",
      "published_at": "2024-01-29T16:52:53.476Z",
      ...
   },
   "cv": 1630693219,
   "rels": [],
   "links": []
}
    

New Fields in Content Delivery API V2

• cv
• rels
• links

Parameter Changes

In Content Delivery API V2, several parameter changes have been introduced for listing and getting stories, providing users with more flexibility and control over queries.

Parameters for listing stories:

Here are the updated parameters for listing stories.

• content_type
• level
• by_ids
• resolve_assets

Parameters for getting a single story:

Here are the updated parameters for getting a single story.

• resolve_assets
• content_type

Read more about getting and listing stories in the Content Delivery API V2 documentation.

Resolving Relations and Links:

Resolving Relations: In Content Delivery API V2, relations are not nested anymore; they are serialized in the rels array returned in the JSON response. resolve_relations is two levels deep in the Content Delivery API V2. You can learn more about resolving relations.

Resolving Links: When using the resolve_links parameter in Content Delivery API V2, the links are serialized in the links array returned in the JSON response. The response also contains the cv value. A new value for resolve_links has also been introduced in Content Delivery API V2, which is link and this also returns the translated slugs. You can learn more about resolving links and the link object history.