header

contentful.rb - Contentful Ruby Delivery Library

Ruby library for the Contentful Content Delivery API and Content Preview API. It helps you to easily access your Content stored in Contentful with your Ruby applications.

What is Contentful?

Contentful provides content infrastructure for digital teams to power websites, apps, and devices. Unlike a CMS, Contentful was built to integrate with the modern software stack. It offers a central hub for structured content, powerful management and delivery APIs, and a customizable web app that enable developers and content creators to ship their products faster.

<details> <summary>Table of contents</summary>

contentful.rb - Contentful Ruby Delivery library

</details>

Core Features

Content retrieval through Content Delivery API and Content Preview API.
Synchronization
Localization support
Link resolution
Built in rate limiting recovery procedures
Supports Environments (since v2.6.0 - 16. April 2018)

Getting started

In order to get started with the Contentful Ruby library you'll need not only to install it, but also to get credentials which will allow you to have access to your content in Contentful.

Installation
Your first request
Using this library with the Preview API
Authentication
Documentation & References

Installation

Add to your Gemfile and bundle:

gem 'contentful'

Or install it directly from your console:

gem i contentful

Your first request

The following code snippet is the most basic one you can use to get some content from Contentful with this library:

require 'contentful'

client = Contentful::Client.new(
  space: 'cfexampleapi',  # This is the space ID. A space is like a project folder in Contentful terms
  access_token: 'b4c0n73n7fu1'  # This is the access token for this space. Normally you get both ID and the token in the Contentful web app
)

# This API call will request an entry with the specified ID from the space defined at the top, using a space-specific access token.
entry = client.entry('nyancat')

Using this library with the Preview API

This library can also be used with the Preview API. In order to do so, you need to use the Preview API Access token, available on the same page where you get the Delivery API token, and specify the host of the preview API, such as:

require 'contentful'

client = Contentful::Client.new(
  space: 'cfexampleapi',
  access_token: 'b4c0n73n7fu1',
  api_url: 'preview.contentful.com'
)

You can query for entries, assets, etc. very similar as described in the Delivery API Documentation. Please note, that all methods of the Ruby client library are snake_cased, instead of JavaScript's camelCase:

Authentication

To get your own content from Contentful, an app should authenticate with an OAuth bearer token.

You can create API keys using the Contentful web interface. Go to the app, open the space that you want to access (top left corner lists all the spaces), and navigate to the APIs area. Open the API Keys section and create your first token. Done.

Don't forget to also get your Space ID.

For more information, check the Contentful REST API reference on Authentication.

To help you get the most out of this library, we've prepared all available client configuration options, reference documentation, tutorials and other examples that will help you learn and understand how to use this library.

Configuration

The client constructor supports several options you may set to achieve the expected behavior:

client = Contentful::Client.new(
  # ... your options here ...
)

<table> <thead> <tr> <th>Name</th> <th>Default</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>access_token</code></td> <td></td> <td><strong>Required</strong>. Your access token.</td> </tr> <tr> <td><code>space</code></td> <td></td> <td><strong>Required</strong>. Your space ID.</td> </tr> <tr> <td><code>environment</code></td> <td>'master'</td> <td>Your environment ID.</td> </tr> <tr> <td><code>api_url</code></td> <td><code>'cdn.contentful.com'</code></td> <td>Set the host used to build the request URIs.</td> </tr> <tr> <td><code>default_locale</code></td> <td><code>'en-US'</code></td> <td>Defines default locale for the client.</td> </tr> <tr> <td><code>secure</code></td> <td><code>true</code></td> <td>Defines whether to use HTTPS or HTTP. By default we use HTTPS.</td> </tr> <tr> <td><code>authentication_mechanism</code></td> <td><code>:header</code></td> <td>Sets the authentication mechanisms, valid options are <code>:header</code> or <code>:query_string</code></td> </tr>

Contentful.rb

Install / Use

README