Ruby client for the Contentful Content Management API.
Contentful is a content management platform for web applications, mobile apps and connected devices. It allows you to create, edit & manage content in the cloud and publish it anywhere via powerful API. Contentful offers tools for managing editorial teams and enabling cooperation between organizations.
Add this line to your application's Gemfile:
gem 'contentful-management'
Some examples can be found in the examples/ directory or you take a look at this extended example script.
At the beginning the API client instance should be created for each thread that is going to be used in your application:
client = Contentful::Management::Client.new('access_token')The access token can easily be created through the management api documentation.
Retrieving all spaces:
spaces = Contentful::Management::Space.allRetrieving one space by id:
blog_space = Contentful::Management::Space.find('blog_space_id')Destroying a space:
blog_space.destroyCreating a space:
blog_space = Contentful::Management::Space.new
blog_space.name = 'Blog Space'
blog_space.saveor
blog_space = Contentful::Management::Space.create(name: 'Blog Space')or in the context of the organization (if you have multiple organizations within your account):
blog_space = Contentful::Management::Space.create(name: 'Blog Space', organization_id: 'organization_id')If you want to create a default locale different from en-US:
blog_space = Contentful::Management::Space.create(name: 'Blog Space', default_locale: 'de-DE')Updating a space:
blog_space.update(name: 'New Blog Space')or
blog_space.name = 'New Blog Space'
blog_space.saveRetrieving all content types from a space:
blog_post_content_types = blog_space.content_types.allRetrieving all published content types from a space:
blog_post_content_types = blog_space.content_types.all_publishedRetrieving one content type by id from a space:
blog_post_content_type = blog_space.content_types.find(id)Creating a field for a content type:
title_field = Contentful::Management::Field.new
title_field.id = 'blog_post_title'
title_field.name = 'Post Title'
title_field.type = 'Text'
blog_post_content_type.fields.add(field)or
blog_post_content_type.fields.create(id: 'title_field_id', name: 'Post Title', type: 'Text')- if the field_id exists, the related field will be updated.
or the field of link type:
blog_post_content_type.fields.create(id: 'my_entry_link_field', name: 'My Entry Link Field', type: 'Link', link_type: 'Entry')or the field of an array type:
items = Contentful::Management::Field.new
items.type = 'Link'
items.link_type = 'Entry'
blog_post_content_type.fields.create(id: 'my_array_field', name: 'My Array Field', type: 'Array', items: items)Deleting a field from the content type:
blog_post_content_type.fields.destroy(title_field_id)Creating a content type:
blog_space.content_types.create(name: 'Post', fields: [title_field, body_field])or
blog_post_content_type = blog_space.content_types.new
blog_post_content_type.name = 'Post'
blog_post_content_type.fields = [title_field, body_field]
blog_post_content_type.saveDestroying a content type:
blog_post_content_type.destroyActivating or deactivating a content type:
blog_post_content_type.activate
blog_post_content_type.deactivateChecking if a content type is active:
blog_post_content_type.active?Updating a content type:
blog_post_content_type.update(name: 'Post', description: 'Post Description', fields: [title_field])Retrieving all locales from the space:
blog_post_locales = blog_space.locales.allRetrieving one locale by the locale-id from the space:
blog_post_locale = blog_space.locales.find(locale_id)Creating a locale
blog_space.locales.create(name: 'German', code: 'de-DE')Updating a locale
blog_post_locale.update(name: 'German', code: 'de-DE')Destroying a locale
blog_post_locale.destroyRetrieving all assets from the space:
blog_post_assets = blog_space.assets.allRetrieving all published assets from the space:
blog_post_assets = blog_space.assets.all_publishedRetrieving an asset by id:
blog_post_asset = blog_space.assets.find('asset_id')Creating a file:
image_file = Contentful::Management::File.new
image_file.properties[:contentType] = 'image/jpeg'
image_file.properties[:fileName] = 'example.jpg'
image_file.properties[:upload] = 'http://www.example.com/example.jpg'Creating an asset:
my_image_asset = blog_space.assets.create(title: 'My Image', description: 'My Image Description', file: image_file)or an asset with multiple locales
my_image_localized_asset = space.assets.new
my_image_localized_asset.title_with_locales= {'en-US' => 'title', 'pl' => 'pl title'}
my_image_localized_asset.description_with_locales= {'en-US' => 'description', 'pl' => 'pl description'}
en_file = Contentful::Management::File.new
en_file.properties[:contentType] = 'image/jpeg'
en_file.properties[:fileName] = 'pic1.jpg'
en_file.properties[:upload] = 'http://www.example.com/pic1.jpg'
pl_file = Contentful::Management::File.new
pl_file.properties[:contentType] = 'image/jpeg'
pl_file.properties[:fileName] = 'pic2.jpg'
pl_file.properties[:upload] = 'http://www.example.com/pic2.jpg'
asset.file_with_locales= {'en-US' => en_file, 'pl' => pl_file}
asset.saveProcess an Asset file after create:
asset.process_fileUpdating an asset:
- default locale
my_image_asset.update(title: 'My Image', description: 'My Image Description', file: image_file)- another locale (we can switch locales for the object, so then all fields are in context of selected locale)
my_image_asset.locale = 'nl'
my_image_asset.update(title: 'NL Title', description: 'NL Description', file: nl_image)- field with multiple locales
my_image_asset.title_with_locales = {'en-US' => 'US Title', 'nl' => 'NL Title'}
my_image_asset.saveDestroying an asset:
my_image_asset.destroyArchiving or unarchiving an asset:
my_image_asset.archive
my_image_asset.unarchiveChecking if an asset is archived:
my_image_asset.archived?Publishing or unpublishing an asset:
my_image_asset.publish
my_image_asset.unpublishChecking if an asset is published:
my_image_asset.published?Retrieving all entries from the space:
entries = blog_space.entries.allRetrieving all published entries from the space:
entries = blog_space.entries.all_publishedRetrieving all entries from the space with given content type:
entries = blog_space.entries.all(content_type: content_type.id)or
entries = content_type.entries.allRetrieving an entry by id:
entry = blog_space.entries.find('entry_id')Creating a location:
location = Location.new
location.lat = 22.44
location.lon = 33.33Creating an entry:
- with a default locale
my_entry = blog_post_content_type.entries.create(post_title: 'Title', assets_array_field: [image_asset_1, ...], entries_array_field: [entry_1, ...], location_field: location)- with multiple locales
my_entry = blog_post_content_type.entries.new
my_entry.post_title_with_locales = {'en-US' => 'EN Title', 'pl' => 'PL Title'}
my_entry.saveUpdating an entry:
- with a default locale
my_entry.update(params)- with another locale
entry.locale = 'nl'
entry.update(params)- with multiple locales
my_entry.post_title_with_locales = {'en-US' => 'EN Title', 'pl' => 'PL Title'}
my_entry.saveDestroying an entry:
my_entry.destroyArchiving or unarchiving the entry:
my_entry.archive
my_entry.unarchiveChecking if the entry is archived:
my_entry.archived?Publishing or unpublishing the entry:
my_entry.publish
my_entry.unpublishChecking if the entry is published:
my_entry.published?Entries created with empty fields, will not return those fields in the response. Therefore, Entries that don't have Cache enabled, will need to make an extra request to fetch the Content Type and fill the missing fields. To allow for Content Type Caching:
- Enable Content Type Cache at Client Instantiation time
- Query Entries through
space.entries.findinstead ofEntry.find(space_id, entry_id)
Retrieving all webhooks from the space:
webhooks = blog_space.webhooks.allRetrieving one webhook by the webhook-id from the space:
blog_post_webhook = blog_space.webhooks.find(webhook_id)Creating a webhook
blog_space.webhooks.create(url: 'https://www.example.com', httpBasicUsername: 'username', httpBasicPassword: 'password')Updating a webhook
blog_post_webhook.update(url: 'https://www.newlink.com')Destroying webhook:
blog_post_webhook.destroyRetrieving all api keys from the space:
blog_post_api_keys = blog_space.api_keys.allRetrieving one api key by the api-key-id from the space:
blog_post_api_key = blog_space.api_keys.find(api_key_id)Creating an api key
blog_space.api_keys.create(name: 'foobar key', description: 'key for foobar mobile app')Takes an array of values and validates that the field value is in this array.
validation_in = Contentful::Management::Validation.new
validation_in.in = ['foo', 'bar', 'baz']
blog_post_content_type.fields.create(id: 'valid', name: 'Testing IN', type: 'Text', validations: [validation_in])Takes optional min and max parameters and validates the size of the array (number of objects in it).
validation_size = Contentful::Management::Validation.new
validation_size.size = { min: 10, max: 15 }
blog_post_content_type.fields.create(id: 'valid', name: 'Test SIZE', type: 'Text', validations: [validation_size])Takes optional min and max parameters and validates the range of a value.
validation_range = Contentful::Management::Validation.new
validation_range.range = { min: 100, max: 150 }
blog_post_content_type.fields.create(id: 'valid', name: 'Range', type: 'Text', validations: [validation_range])Takes a string that reflects a JS regex and flags, validates against a string. See JS Reference for the parameters.
validation_regexp = Contentful::Management::Validation.new
validation_regexp.regexp = {pattern: '^such', flags: 'im'}
blog_post_content_type.fields.create(id: 'valid', name: 'Regex', type: 'Text', validations: [validation_regexp])Takes an array of content type ids and validates that the link points to an entry of that content type.
validation_link_content_type = Contentful::Management::Validation.new
validation_link_content_type.link_content_type = ['post_content_type_id']
blog_post_content_type.fields.create(id: 'entry', name: 'Test linkContentType', type: 'Entry', validations: [validation_link_content_type])Takes a MimeType group name and validates that the link points to an asset of this group.
validation_link_mimetype_group = Contentful::Management::Validation.new
validation_link_mimetype_group.link_mimetype_group = 'image'
content_type.fields.create(id: 'asset', validations: [validation_link_mimetype_group])Validates that a value is present.
validation_present = Contentful::Management::Validation.new
validation_present.present = true
content_type.fields.create(id: 'number', validations: [validation_present])Validates that the property is a link (must not be a valid link, just that it looks like one).
validation_link_field = Contentful::Management::Validation.new
validation_link_field.link_field = true
content_type.fields.create(id: 'entry', validations: [validation_link_field])blog_space.entries.all(limit: 5).next_page
blog_space.assets.all(limit: 5).next_page
blog_space.entries.all(limit: 5).next_pageLogging is disabled by default, it can be enabled by setting a logger instance and a logging severity.
client = Contentful::Management::Client.new('access_token', logger: logger_instance, log_level: Logger::DEBUG)Example loggers:
Rails.logger
Logger.new('logfile.log')The default severity is set to INFO and logs only the request attributes (headers, parameters and url). Setting it to DEBUG will also log the raw JSON response.
If :raise_errors is set to true, an Exception will be raised in case of an error. The default is false, in this case a Contentful::Management::Error object will be returned.
client = Contentful::Management::Client.new('access_token', raise_errors: true)This allows for fetching Content Types for your Space at Client instantiation time, which prevents extra requests per Entry. To enable this, in your Client instantiation do:
Contentful::Management::Client.new(token, dynamic_entries: ['my_space_id'])You can enable the Cache for as many Spaces as you want.
- Fork it ( https://github.com/[my-github-username]/contentful-management/fork )
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request