Getting Started with Contentful and JavaScript

Get started using our JavaScript client library to consume content.

Contentful's Content Delivery API (CDA) is a read-only API for retrieving content from Contentful. All content, both JSON and binary, is fetched from the server closest to a user's location by using our global CDN.

We publish client libraries for various languages to make developing applications easier.

Requirements

This tutorial assumes that you understand the Contentful data model.

Authentication

For every request, clients need to provide an API key, which is created per space and used to delimit applications and content classes.

You can create an access token using the Contentful web app or the Content Management API.

Set up the client

First you need to get the client library and include it in your project.

• In Node.js, install the npm package and require it in your code:

  npm install contentful

  // main.js
  var contentful = require('contentful');

• In a web browser, there are multiple ways you can get the client library. The quickest way is to use the pre-built and minified JavaScript file from a CDN:

  <script src="https://cdn.jsdelivr.net/npm/contentful@latest/dist/contentful.browser.min.js"></script>

  The recommended but longer way is to manage your browser JavaScript code and dependencies with npm and use a build tool such as browserify or webpack.

  In this case, first install the package:

  npm install contentful

  Then you can use it in your code:

  // main.js
  var contentful = require('contentful');

  And build and use your file:

  webpack main.js bundle.js
  # or
  browserify main.js -o bundle.js

  <script src="bundle.js"></script>

Initialize the client

You need an API key and a space ID to initialize a client. You can use the API key and space ID pre-filled below from our example space or replace them with your own values.

var client = contentful.createClient({
  space: '<space_id>',
  accessToken: '<access_token>',
});

Read the reference documentation for more options on initializing the client.

Request a single entry

Once you have a client you can start getting content.

To retrieve a specific entry, you need the ID for that entry. If you're looking at an entry you created in the Contentful web app, it should be the string in the URL after /entries/. In this example the entry has an id of <entry_id>.

client.getEntry('<entry_id>').then(function (entry) {
  // logs the entry metadata
  console.log(entry.sys);

  // logs the field with ID title
  console.log(entry.fields.productName);
});

Playsam Streamliner Classic Car, Espresso

The object received by the Promise callback represents the Entry <entry_id> and contains two objects: sys, describing system properties of the entry, and fields, assigning specific values to the fields of its content type ('Product').

For more details on the information contained on sys read the common resource attributes guide in the CDA reference or the entities definitions in the client library reference

Retrieve all entries of a space

Now you're going to retrieve all the entries in a space.

client.getEntries().then(function (entries) {
  // log the title for all the entries that have it
  entries.items.forEach(function (entry) {
    if (entry.fields.productName) {
      console.log(entry.fields.productName);
    }
  });
});

Whisk Beater
Playsam Streamliner Classic Car, Espresso
Hudson Wall Cup
SoSo Wall Clock

It's similar to getting a single entry, except you get an array with all the retrieved entries, and parameters relevant to pagination.

By default you get 100 entries. If you'd like to retrieve more, you can skip the first 100. You can retrieve more than 100 entries per request, up to 1000.

client
  .getEntries({
    skip: 100,
    limit: 200,
    order: 'sys.createdAt',
  })
  .then(function (entries) {
    console.log(entries.items.length); // 200
  });

You can specify an ordering parameter to get more predictable results. You can read more about ordering parameters in the search parameters reference guide.

Retrieve linked entries

Entries have links to other entries, so when you retrieve a list of entries, those links are automatically resolved so you don't have to retrieve the linked entry separately.

By default, Contentful resolves one level of linked entries or assets.

The following example demonstrates the usage of a linked asset on field logo for the 'brand' content type you can find in our product catalog example space:

client.getEntries().then(function (entries) {
  entries.items.forEach(function (entry) {
    if (entry.fields.companyName) {
      console.log(entry.fields.logo.fields.file.url);
    }
  });
});

{"url":"//images.ctfassets.net/71rop70dkqaj/2Y8LhXLnYAYqKCGEWG4EKI/44105a3206c591d5a64a3ea7575169e0/lemnos-logo.jpg","details":{"size":7149,"image":{"width":175,"height":32}},"fileName":"lemnos-logo.jpg","contentType":"image/jpeg"}
{"url":"//images.ctfassets.net/71rop70dkqaj/3wtvPBbBjiMKqKKga8I2Cu/90b69e82b8b735383d09706bdd2d9dc5/zJYzDlGk.jpeg","details":{"size":12302,"image":{"width":353,"height":353}},"fileName":"zJYzDlGk.jpeg","contentType":"image/jpeg"}
{"url":"//images.ctfassets.net/71rop70dkqaj/4zj1ZOfHgQ8oqgaSKm4Qo2/8c30486ae79d029aa9f0ed5e7c9ac100/playsam.jpg","details":{"size":7003,"image":{"width":100,"height":100}},"fileName":"playsam.jpg","contentType":"image/jpeg"}

If you'd like to resolve additional levels of links, or none at all, use the include parameter. The example below resolves no links, and only contains metadata about the image, so will return an error:

client.getEntries({ include: 0 }).then(function (entries) {
  // log the file url of any linked assets on field `image`
  entries.items.forEach(function (entry) {
    if (entry.fields.companyName) {
      console.log(JSON.stringify(entry.fields.logo.fields.file.url));
    }
  });
});

You can turn off link resolution when you initialize the client library or with a resolveLinks property on every request.

Read the links reference guide for more information.

Retrieve entries with search parameters

The entries method can take parameters for filtering and querying. You can use these same parameters when getting assets or content types.

The following request filters all entries by a specific content type, using that content type's ID.

You can use the content type pre-filled below for our example space or replace it with your own value.

The example below filters entries to the 'Brand' content type:

client
  .getEntries({
    content_type: '<brand_content_type_id>',
  })
  .then(function (entries) {
    console.log(JSON.stringify(entries));
    entries.items.forEach(function (entry) {
      console.log(JSON.stringify(entry.fields.companyName));
    });
  });

"Normann Copenhagen"
"Lemnos"
"Playsam"

You can filter by properties of your entries, for example, a product SKU:

client
  .getEntries({
    'fields.sku': '<sku_value>',
    content_type: '<product_content_type_id>',
  })
  .then(function (entries) {
    entries.items.forEach(function (entry) {
      console.log(JSON.stringify(entry.fields.sku));
    });
  });

"B00E82D7I8"

Apart from equality filters, you can use operators. The example below is the reverse of the previous example, giving you any entries where fields.sku is not equal ([ne]) to the specified value.

client
  .getEntries({
    'fields.sku[ne]': '<sku_value>',
    content_type: '<product_content_type_id>',
  })
  .then(function (entries) {
    entries.items.forEach(function (entry) {
      console.log(JSON.stringify(entry.fields.sku));
    });
  });

"B00MG4ULK2"
"B0081F2CCK"
"B001R6JUZ2"

See also

To learn about other filters and parameters that you can use, read the following documentation:

• Equality/inequality (as well as in array fields)
• Inclusion/exclusion
• Ranges
• Full text search
• Geo location searches
• CDA search parameters