How to Query the API with Javascript

In order to retrieve the content from your repository, you will need to query the repository API. When you create your query you will specify exactly what it is you are looking for. You could query the repository for all the documents of certain type or retrieve the one specific document you need.

Let’s take a look at how to put together queries for whatever case you need.

Check out the Integrating with an existing Javascript project page to learn how to get set up to query documents.

The Basics

When retrieving content from your prismic.io repository using javascript, here's what a typical query looks like:

Copy
var Prismic = require('prismic-javascript');

Prismic.getApi("https://your-repository-name.prismic.io/api/v2",  { req: req }).then(function(api) {
  return api.query(
    Prismic.Predicates.at('document.type', 'blog-post'),
    { orderings : '[my.blog-post.date desc]' }
  );
}).then(function(blogPosts) {
  // blogPosts is the response object, blogPosts.results holds the documents
});

This is the basic format of a query. In the query you have two parts, the Predicate and the options.

You can omit the `req` parameter if you're doing your queries on the client side (React.js, Angular.js, etc)

Using the API server-side

It comes handy to use the `initAPI` helper function if you're doing your query from the server side (like in Node.js)

Should I call `initApi` on every query?

The `initAPI` call returns the API object and is required to get the latest version of your content. You should call `initApi` to retrieve the API object on every request, page, or screen. It is recommended to assign the API object to a variable, and use it for all queries of the same screen.

Why does `initApi` call requires a `req` parameter?

prismic.io has the capacity to do unlimited different preview sessions for different drafts or releases. To offer this and other powerful functionalities, like A/B testing, prismic.io uses a cookie that it assigns to the `req` object.

Simply providing `req` to the API enables unlimited previews, A/B testing and other upcoming powerful features.

You can omit the `req` parameter if you're performing your queries for the client-side (ex: React.js, Angular.js). The API will be able to retrieve the required token on its own.

Predicates

Predicates are a powerful way to query your content. In the above example we had the following predicate:

Copy
Prismic.Predicates.at('document.type', 'blog-post')

The predicate(s) will define which documents are retrieved from the content repository. This particular example will retrieve all of the documents of the type "blog-post".

The first part, "document.type" is the path, or what the query will be looking for. You will find a list and description of the available paths on the Query Predicates Reference page. The second part the predicate in the above example is "blog-post" this is the value that the query is looking for.

You can combine more than one predicate together to refine your query. You just need to put all your predicates into a comma-separated array like the following example:

Copy
[ Prismic.Predicates.at('document.type', 'blog-post'),
  Prismic.Predicates.at('document.tags', ['featured']) ]

This particular query will retrieve all the documents of the "blog-post" type that also have the tag "featured".

You will find a list and description of all the available predicates on the Query Predicates Reference page.

Options

In the second part of the query, you can include the options needed for that query. In the above example we had the following options.

Copy
{ orderings : '[my.blog-post.date desc]' }

This specifies how the returned list of documents will be ordered. You can include more than one option, by comma separating them as shown below:

Copy
{ pageSize : 10, page : 2 }

You will find a list and description of all the available options on the Query Options Reference page.

Here's another example of a more advanced query with multiple predicates and multiple options:

Copy
var Prismic = require('prismic-javascript');

Prismic.api("https://your-repository-name.prismic.io/api/v2").then(function(api) {
  return api.query(
    [ Prismic.Predicates.at('document.type', 'blog-post'),
      Prismic.Predicates.at('document.tags', ['featured'])], 
    { pageSize : 25, page : 1, orderings : '[my.blog-post.date desc]' }
  );
}).then(function(featuredPosts) {
  // featuredPosts is the response object, featuredPosts.results holds the documents
});

Whenever you query your content, you end up with the response object stored in the defined variable. In this case the response object is stored in the featuredPosts variable.