Starting April 1st, the main Prismic API endpoint (/api/v2) will no longer include a list of all the tags used in a repo.

Tags will still be available in your Prismic repository, you will still be able to query by tag, and tags will remain on individual documents returned from the API (via /api/v2/search).

Currently, your main endpoint looks something like this:

{
  "refs": [...],
  "integrationFieldsRef": "...",
  "bookmarks": {...},
  "types": {...},
  "languages": [...],
  "tags": [
    "Clothing",
    "Housewares",
    "Electronics",
  ],
  "forms": {},
  // ...
}

After this change, the main endpoint will continue to include a "tags" property, with an empty array as its value:

{
  "refs": [...],
  "integrationFieldsRef": "...",
  "bookmarks": {...},
  "types": {...},
  "languages": [...],
  "tags": [],
  "forms": {},
  // ...
}

The reason for the change

Every content query to the Prismic API involves two API requests:

1. The first request goes to your main API endpoint: /api/v2. This endpoint doesn't include any content. It only includes information about your repo. With this query, you retrieve a ref. A ref is the ID for the most recent version of your content.
2. The second query goes to your content API, and includes ref from your first query: /api/v2/search. The ref ensures that the API returns the most recent version of your content, and prevents the API from serving stale cached content.

This two-request process is key to our rapid API response times.

Currently, when you make your first request, the API response includes a list of all of the tags included in your repo. If a repository has many tags, it can take time to generate the list. Since 99.9% of requests to the main API endpoint are only performed to retrieve a ref, the tag list is unnecessary.

By removing the tag list, content queries for repos with lots of tags will get faster. It will also streamline our API architecture, enabling us to make further improvements.

What you need to do

In surveys of our users, we've found that very few use the tag list. If you do use the tag list, you should remove that usage from your app.

For now, the tag list will be partially deprecated. We will leave the "tags" property in the response, and it will contain an empty array. This will help prevent errors in projects that use the tags list.

Eventually, we will remove the "tags" property completely. We will provide notice before that happens.

How we're speeding up the API

This change is part of a large, ongoing project to speed up our API response times. Part of the reason for the tags change is because we're moving our /api and /api/v2 endpoints to an Edge CDN, making requests locally available around the world.

If you want to learn more about how we optimize our API, watch our February product meet-up, where we discussed the architecture behind Prismic.