By the end of this tutorial, you will master all the different ways of getting content out of Contentful CMS. Out of the box, you will have access to the Content Delivery API, the Content Management API, GraphQL, and the User Management API. On top of that, there are also 8 different SDKs, a number of JavaScript packages, as well as some handy marketplace apps that you can make use of to make content creation easier.

Trying to figure out which is the optimal API to use in your exact situation, can be daunting. If you are currently stuck in this exact situation, this article has your back. If you are looking for a simple guide, that will explain all the basics required in order to start building a kick-ass headless website, or a mobile app using Contentful CMS, then read on 🔥🔥🔥

Contentful Toolkit Overview

Before we dive into the details, let us take a quick overview of some of the tools that you can make use of during a Contentful build. First, within Contentful you have access to a number of SDKs, these include:

If you are additionally working within a JavaScript project, it is also worth knowing about these handy NPM packages:

Finally, there are also some handy dev tools and marketplace apps that you can make good use of as well:

Now that you have access to all the Contentful tools that you need to be successful, let us now look at the different ways that you can talk to Contentful. The first option that we will look at is a classic, using the REST API to get access to CMS content!

Content Delivery API

The most common way to get data from the CMS is to use the Contentful Content Delivery API. You can opt to manually call the Content Delivery API directly, alternatively, you might want to make use of the official Contentful JavaScript NPM package. The JavaScript package, in essence, creates a wrapper around the API that you can then make use of within your codebase to make calling Contentful super easy. In order to install this package, you can run this command:

The first thing that you need to know in order to master this API is that without supplying the correct validation inputs your API request will fail. Regardless of which API or technique that you want to use, in order to establish a successful connection you will always need to supply these additional parameters with the API request:

  • Access tokens
  • Space ID
  • Environment name

Watch the related video above to learn how to get these within the CMS. Armed with these values you are free to make lots of calls to the CMS. In order to get content there are two main API end-points you need to know about, however, in terms of best practice, I'd recommend favoring one.

These API calls then map back to the Contentful Javascript package, like this:

It is worth pointing out that within this code you still need to supply an access token and a space ID. By default, the JavaScript package will default to the master environment. This means that you can omit the environment name at the code level if you are not making use of environments on your project. If you use the REST API you will not have this luxury and for those calls supplying the environment name is mandatory

GraphQL

When it comes to accessing your content within your application, you have two choices. Do you want to access the content over an API, or, would you like to query for content using GraphQL instead?

Using GraphQL will allow you to build very specific and targeted queries. This means that using GraphQL should give your application both performance and security benefits as it will enable you to return only the information, or operations that you need. This in turn should significantly reduce the amount of data being sent from the CMS to your website. It will also mean that you are not exposing content to the client that is not needed.

To get going with GraphQL on your project, you do not need to install anything specifically. All you need to do is send requests to https://graphql.contentful.com, et the returned JSON and then render it on a page. Code-wise can you query the GraphQL end-point like this:

As GraphQL involves implementing custom queries, it is impossible for Contentful to create reusable functions that you can use. This means that a GraphQL implementation will be very custom to how you modeled the CMS at that point in time. If you need to update your content models within the CMS, your code will need to be updated as well.

The benefit of using the getEntries() function is that by using reflection, your code can automatically reflect updates if that is your wish. The REST API also gives you more options to configure things out of the box.

The trade-off is that you get more JSON returned and your web vitals will likely be slower assuming you render using SSR and not SSG!). One of the challenges of working with GraphQL is figuring out the syntax for the query that you want to use. You could try doing this within your code, however, it will feel like a faff. Instead, a much more convenient way to access this IDE is to make use of a marketplace app called GraphQL Playground.

You can install the GraphQL Playground for free via the Contentful marketplace. In order to successfully install the plug-in, you will need to provide it with the access token, however, after doing this for the first time, you can then use the GraphQL Playground without the need for remembering URLs, or, access tokens ever again!

Content Mangement API

The Contentful Content Delivery API only exposes read-only end-points. When your only task is to render CMS content on a webpage, this makes perfect sense as you will only need to perform read-only operations. Making the API read-only not only makes your website more secure, it will also be marginally faster as caching is easier to implement. Every so often you will bump into a requirement where you will need to write some data back into the CMS. A good example of when this use case could occur is when you want to allow site visitors to make comments on your website.

If you need to write data to the CMS, you will need to make use of an alternative API called the Content Management API. The Content Management API is more focused on admin-level tasks like managing spaces, content, content-types, and environments.

Just like the Content Delivery API, there are two ways you can access the Management API. You can query the API directly, or you can access it via an SDK. The JavaScript library that wraps the Content Management API is called contentful-management. The functions exposed by this package mirror the endpoints of the Content Management API. For reference, you can find the only documentation around this package here. To install this package in your project, you can use this command:

The big difference with using this API is that you will need to use a special admin access token. This token is not the same one as you use for the Content Delivery API. In order to generate an admin access token, log back into the CMS, and within the Settings menu tab located in the top menu, click on the API Keys menu item. You may not have noticed this before, but the API Keys screen will open on the Content delivery/preview token tab by default. To generate an admin token, you will need to switch tabs. You can do that by clicking on the Content management tokens tab. From this new screen, you can generate an admin access token, and voila!

The Content Management API will allow you to interact with things like:

  • Spaces
  • Environments
  • Organizations
  • Content types
  • Entries
  • Assets
  • Locales
  • Tags
  • Teams
  • Users
  • Releases
  • App Actions
  • Workflows

For each-end point, you can perform all the standard CRUD operations (create, update, read, delete). By changing the request type to either a GET, PUT, DELETE, or a `POST. I recommend reading the API documentation to learn the exact syntax as it covers a lot!

User Mangement API

Another advanced requirement that you may bump into at some point is the need to remotely manage your content editors and the permissions that are assigned to them. The good news is that this is possible via the User Management API.

To get going with the user management API, you will be making requests to api.contentful.com. In order to successfully connect to Contentful, you will need to add a valid admin access token within the request header. See the section above if you are unsure how to do that.

After querying the API, the returned JSON will include related meta-data within the sys object, as well as any pagination properties where applicable. The user management API covers a broad range of management capabilities including endpoints to manage organizations, teams, members, and roles.

Just like the other Contentful APIs, the user management API adheres to the REST standard. For each specific entity type that you want to work with, the API contains GET endpoints to query either for a list or an individual item. A PUT endpoint to update an existing item and a DELETE endpoint to delete an existing item.

As you have seen, Contentful ships with a number of different techniques and tools that will allow you to get data from the CMS and render it within a website and app. Hopefully, this guide will give you some insights that will help you to be able to ramp up more quickly on a Contentful project.

If you want to learn more about Contentful you can check out my book here which I think is epic. Happy Coding 🤘