API versioning in Javascript Client
In order to promote incremental changes, the Sanity API is versioned based on ISO dates (YYYY-MM-DD) in the UTC timezone.
Gotcha
The apiVersion property of the JavaScript client is currently optional. If no value is provided, the client will issue a deprecation warning and default to using v1 of the API.
Unless you know of a specific API version you want to use, you'll want to set it to today's UTC date. By doing this, you'll get all the latest bug fixes and features, while preventing any timezone confusion and locking the API to prevent breaking changes.
What does the apiVersion date mean?
Essentially, the date you enter for the apiVersion will use the API as it worked on that date. You can confidently use features that were added on or before that date, and any breaking changes implemented after that date will not affect your use of the API.
Note: While it's tempting to use a date that's been set dynamically as an API version, this can be a risky idea. Using a static (i.e., hard coded) date, you pin your project to a specific version of the API, which prevents any sudden changes that can break your implementation. If you hard code your API to v2021-08-31, and it works, you can be assured it will continue to work even as new API versions are released.
Protip
Recommended: apiVersion: '2021-08-31'
Not recommended: apiVersion: new Date().toISOString().slice(0, 10)
In future versions, specifying an API version will be required. For now, to maintain backward compatibility, not specifying a version will trigger a deprecation warning and fall back to using v1.
Gotcha
When using the HTTP API, the version number is prefixed with the v character (v1, v2021-08-31, etc.). In the JavaScript client, no prefix is needed (apiVersion: '2021-08-31').
Example usage
import sanityClient from '@sanity/client'
const client = sanityClient({
projectId: 'your-project-id',
dataset: 'production',
apiVersion: '2021-08-31', // use a UTC date string
token: 'sanity-auth-token', // or leave blank for unauthenticated usage
useCdn: true, // `false` if you want to ensure fresh data
})Was this page helpful?