Getting Started with Contentful and Ruby

This guide will show you how to get started using our Ruby 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.

Installation

First, install the 'contentful' gem, with the terminal:

gem install contentful

Or you can add it to your Gemfile:

gem 'contentful'

And run bundle install to install the gem and all its dependencies.

Setting up the Contentful client

Once you have installed the gem, you can start using it inside your application.

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.

require 'contentful'

client = Contentful::Client.new(
  space: '<space_id>',
  access_token: '<access_token>',
  dynamic_entries: :auto
)

Getting your content

Contentful separates content between entries, which contain your data and relationships with other content or images, and assets, which represent static content, like images, and are served as files. Read more in our content model guide.

Entries

With the client created, you can now start consuming data from the API.

For example, to request all entries in a space from the API:

entries = client.entries

entries.each do |entry|
  if entry.fields[:productName]
    puts entry.fields[:productName]
  end
end

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

Or to request a single entry:

entry_id = '<entry_id>'
classic_car = client.entry(entry_id)

puts classic_car.fields[:productName]

Playsam Streamliner Classic Car, Espresso

You can specify any of the query parameters accepted by the API, for example:

products_by_price = client.entries(content_type: '<product_content_type_id>', order: 'fields.price')

products_by_price.each do |entry|
  if entry.fields[:productName]
    puts entry.fields[:productName]
  end
end

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

Using your entry as a Ruby object

Once you have your entry, you can use it as a Ruby object that follows standard Ruby conventions:

puts product.product_name
puts "it costs #{product.price}"
puts "I am tagged with #{product.tags.join(' and ')}"

Playsam Streamliner Classic Car, Espresso
it costs 44
I am tagged with wood and toy and car and sweden and design

You can form complicated queries and interactions with your entries:

products_with_many_tags = client.entries(content_type: '<content_type>', include: 2).select { |product| product.tags.size > 2 }
products_with_many_tags.each do |product|
  puts "I am tagged with #{product.tags.join(' and ')}"
  puts "My brand is #{product.brand.company_name}"
end

I am tagged with vase and flowers and accessories
My brand is: Normann Copenhagen
I am tagged with wood and toy and car and sweden and design
My brand is: Playsam
I am tagged with kitchen and accessories and whisk and scandinavia and design
My brand is: Normann Copenhagen
I am tagged with home décor and clocks and interior design and yellow and gifts
My brand is: Lemnos

In this example you added the include: 2 parameter, which allows the API to resolve links to other related entries.

Using assets

You query assets in a similar way to entries, but the CDA offers more specific features, such as filtering by the type of file. You can also use our Images API, that allows you to manipulate images as you retrieve them.

To query for a single asset:

asset_file = client.asset('<asset_id>').image_url
puts asset_file

//images.ctfassets.net/71rop70dkqaj/wtrHxeu3zEoEce2MokCSi/e86a375b7ad18c25e4ff55de1eac42fe/quwowooybuqbl6ntboz3.jpg

To query all assets in a space:

assets = client.assets

assets.each do |asset|
  puts asset.image_url
end

//images.ctfassets.net/71rop70dkqaj/1MgbdJNTsMWKI0W68oYqkU/4c2d960aa37fe571d261ffaf63f53163/9ef190c59f0d375c0dea58b58a4bc1f0.jpeg
//images.ctfassets.net/71rop70dkqaj/4zj1ZOfHgQ8oqgaSKm4Qo2/8c30486ae79d029aa9f0ed5e7c9ac100/playsam.jpg
//images.ctfassets.net/71rop70dkqaj/3wtvPBbBjiMKqKKga8I2Cu/90b69e82b8b735383d09706bdd2d9dc5/zJYzDlGk.jpeg
//images.ctfassets.net/71rop70dkqaj/wtrHxeu3zEoEce2MokCSi/e86a375b7ad18c25e4ff55de1eac42fe/quwowooybuqbl6ntboz3.jpg
//images.ctfassets.net/71rop70dkqaj/6t4HKjytPi0mYgs240wkG/b7ba3984167c53d728e7533e54ab179d/toys_512pxGREY.png
//images.ctfassets.net/71rop70dkqaj/10TkaLheGeQG6qQGqWYqUI/13c64b63807d1fd1c4b42089d2fafdd6/ryugj83mqwa1asojwtwb.jpg
//images.ctfassets.net/71rop70dkqaj/Xc0ny7GWsMEMCeASWO2um/190cc760e991d27fba6e8914b87a736d/jqvtazcyfwseah9fmysz.jpg
//images.ctfassets.net/71rop70dkqaj/2Y8LhXLnYAYqKCGEWG4EKI/44105a3206c591d5a64a3ea7575169e0/lemnos-logo.jpg
//images.ctfassets.net/71rop70dkqaj/6m5AJ9vMPKc8OUoQeoCS4o/07b56832506b9494678d1acc08d01f51/1418244847_Streamline-18-256.png
//images.ctfassets.net/71rop70dkqaj/6s3iG2OVmoUcosmA8ocqsG/b55b213eeca80de2ecad2b92aaa0065d/1418244847_Streamline-18-256__1_.png
//images.ctfassets.net/71rop70dkqaj/KTRF62Q4gg60q6WCsWKw8/ae855aa3810a0f6f8fee25c0cabb4e8f/soso.clock.jpg