# Contentful::Management [![Gem Version](https://badge.fury.io/rb/contentful-management.svg)](http://badge.fury.io/rb/contentful-management) [![CircleCI](https://circleci.com/gh/contentful/contentful-management.rb/tree/master.svg?style=svg)](https://app.circleci.com/pipelines/github/contentful/contentful-management.rb?branch=master) Ruby client for the Contentful Content Management API. [Contentful](https://www.contentful.com) provides a content infrastructure for digital teams to power content in 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 digital products faster. ## Setup Add this line to your application's Gemfile: ```ruby gem 'contentful-management' ``` ## Usage ### Examples Some examples can be found in the `examples/` directory or you take a look at this [extended example script](https://github.com/contentful/cma_import_script). ### Client At the beginning the API client instance should be created for each thread that is going to be used in your application: ```ruby require 'contentful/management' client = Contentful::Management::Client.new('access_token') ``` The access token can easily be created through the [management api documentation](https://www.contentful.com/developers/documentation/content-management-api/#getting-started). ### Spaces Retrieving all spaces: ```ruby spaces = client.spaces.all ``` Retrieving one space by ID: ```ruby blog_space = client.spaces.find('blog_space_id') ``` Destroying a space: ```ruby blog_space.destroy ``` Creating a space: ```ruby blog_space = client.spaces.new blog_space.name = 'Blog Space' blog_space.save ``` or ```ruby blog_space = client.spaces.create(name: 'Blog Space') ``` or in the context of the organization (if you have multiple organizations within your account): ```ruby blog_space = client.spaces.create(name: 'Blog Space', organization_id: 'organization_id') ``` If you want to create a default locale different from `en-US`: ```ruby blog_space = client.spaces.create(name: 'Blog Space', default_locale: 'de-DE') ``` Updating a space: ```ruby blog_space.update(name: 'New Blog Space') ``` or ```ruby blog_space.name = 'New Blog Space' blog_space.save ``` ### Environments Retrieving all environments: ```ruby environments = client.environments('space_id').all ``` Or if you already have a fetched space: ```ruby environments = space.environments.all ``` Retrieving one environment by ID: ```ruby environment = client.environments('space_id').find('master') ``` Destroying a environment: ```ruby environment.destroy ``` Creating an environment: ```ruby environment = client.environments('space_id').new environment.id = 'dev' environment.name = 'Development' environment.save ``` or ```ruby environment = client.environments(space_id).create(id: 'dev', name: 'Development') ``` Creating an evironment with a different source: ```ruby environment = client.environments(space_id).create(id: 'dev', name: 'Development', source_environment_id: 'other_environment') ``` Updating a environment: ```ruby environment.update(name: 'New Blog environment') ``` or ```ruby environment.name = 'Dev' environment.save ``` ### Assets Retrieving all assets from the environment: ```ruby blog_post_assets = environment.assets.all ``` Retrieving an asset by id: ```ruby blog_post_asset = environment.assets.find('asset_id') ``` Creating a file: ```ruby 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: ```ruby my_image_asset = environment.assets.create(title: 'My Image', description: 'My Image Description', file: image_file) ``` or an asset with multiple locales ```ruby my_image_localized_asset = environment.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.save ``` Process an asset file after create: ```ruby asset.process_file ``` Updating an asset: - default locale ```ruby 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) ```ruby my_image_asset.locale = 'nl' my_image_asset.update(title: 'NL Title', description: 'NL Description', file: nl_image) ``` - field with multiple locales ```ruby my_image_asset.title_with_locales = {'en-US' => 'US Title', 'nl' => 'NL Title'} my_image_asset.save ``` Destroying an asset: ```ruby my_image_asset.destroy ``` Archiving or unarchiving an asset: ```ruby my_image_asset.archive my_image_asset.unarchive ``` Checking if an asset is archived: ```ruby my_image_asset.archived? ``` Publishing or unpublishing an asset: ```ruby my_image_asset.publish my_image_asset.unpublish ``` Checking if an asset is published: ```ruby my_image_asset.published? ``` Checking if has been updated from last published version: ```ruby my_image_asset.updated? ``` ### File Uploads Creating an upload from a file path: ```ruby upload = client.uploads('space_id').create('/path/to/file.md') ``` Alternatively, create it from an `::IO` object: ```ruby File.open('/path/to/file.md', 'rb') do |file| upload = client.uploads('space_id').create(file) end ``` Finding an upload: ```ruby upload = client.uploads('space_id').find('upload_id') ``` Deleting an upload: ```ruby upload.destroy ``` Associating an upload with an asset: ```ruby # We find or create an upload: upload = client.uploads('space_id').find('upload_id') # We create a File object with the associated upload: file = Contentful::Management::File.new file.properties[:contentType] = 'text/plain' file.properties[:fileName] = 'file.md' file.properties[:uploadFrom] = upload.to_link_json # We create the Link from the upload. # We create an asset with the associated file: asset = client.assets('space_id', 'environment_id').create(title: 'My Upload', file: file) asset.process_file # We process the file, to generate an URL for our upload. ``` ### Entries Retrieving all entries from the environment: ```ruby entries = environment.entries.all ``` Retrieving all entries from the environment with given content type: ```ruby entries = environment.entries.all(content_type: content_type.id) ``` or ```ruby entries = content_type.entries.all ``` Retrieving an entry by ID: ```ruby entry = environment.entries.find('entry_id') ``` Retrieving entries by any other field value: ```ruby entries = environment.entries.all(content_type: content_type.id, 'fields.fieldName' => 'value') ``` Note: all [search parameters](https://www.contentful.com/developers/docs/references/content-management-api/#/reference/search-parameters) are supported. Creating a location: ```ruby location = Location.new location.lat = 22.44 location.lon = 33.33 ``` Creating an entry: - with a default locale ```ruby 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 ```ruby my_entry = blog_post_content_type.entries.new my_entry.post_title_with_locales = {'en-US' => 'EN Title', 'pl' => 'PL Title'} my_entry.save ``` Updating an entry: - with a default locale ```ruby my_entry.update(params) ``` - with another locale ```ruby entry.locale = 'nl' entry.update(params) ``` - with multiple locales ```ruby my_entry.post_title_with_locales = {'en-US' => 'EN Title', 'pl' => 'PL Title'} my_entry.save ``` Destroying an entry: ```ruby my_entry.destroy ``` Archiving or unarchiving the entry: ```ruby my_entry.archive my_entry.unarchive ``` Checking if the entry is archived: ```ruby my_entry.archived? ``` Publishing or unpublishing the entry: ```ruby my_entry.publish my_entry.unpublish ``` Checking if the entry is published: ```ruby my_entry.published? ``` Checking if the entry has been updated from last publish: ```ruby my_entry.updated? ``` > 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](#content-type-cache) at client instantiation time > * Query entries through `environment.entries.find` instead of `Entry.find(environment_id, entry_id)` ### Content Types Retrieving all content types from a environment: ```ruby blog_post_content_types = environment.content_types.all ``` Retrieving all published content types from a environment: ```ruby blog_post_content_types = environment.content_types.all_published ``` Retrieving one content type by ID from a environment: ```ruby blog_post_content_type = environment.content_types.find(id) ``` Creating a field for a content type: ```ruby 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 ```ruby 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: ```ruby 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: ```ruby 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: ```ruby blog_post_content_type.fields.destroy(title_field_id) ``` Creating a content type: ```ruby environment.content_types.create(name: 'Post', fields: [title_field, body_field]) ``` or ```ruby blog_post_content_type = environment.content_types.new blog_post_content_type.name = 'Post' blog_post_content_type.fields = [title_field, body_field] blog_post_content_type.save ``` Destroying a content type: ```ruby blog_post_content_type.destroy ``` Activating or deactivating a content type: ```ruby blog_post_content_type.activate blog_post_content_type.deactivate ``` Checking if a content type is active: ```ruby blog_post_content_type.active? ``` Updating a content type: ```ruby blog_post_content_type.update(name: 'Post', description: 'Post Description', fields: [title_field]) ``` ### Validations #### in Takes an array of values and validates that the field value is in this array. ```ruby 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]) ``` #### size Takes optional min and max parameters and validates the size of the array (number of objects in it). ```ruby 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]) ``` #### range Takes optional min and max parameters and validates the range of a value. ```ruby 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]) ``` #### regex Takes a string that reflects a JS regex and flags, validates against a string. See [JS Reference](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp) for the parameters. ```ruby 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]) ``` #### linkContentType Takes an array of content type ids and validates that the link points to an entry of that content type. ```ruby 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]) ``` #### linkMimetypeGroup Takes a MimeType group name and validates that the link points to an asset of this group. ```ruby 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]) ``` #### present Validates that a value is present. ```ruby validation_present = Contentful::Management::Validation.new validation_present.present = true content_type.fields.create(id: 'number', validations: [validation_present]) ``` #### linkField Validates that the property is a link (must not be a valid link, just that it looks like one). ```ruby validation_link_field = Contentful::Management::Validation.new validation_link_field.link_field = true content_type.fields.create(id: 'entry', validations: [validation_link_field]) ``` ### Locales Retrieving all locales from the environment: ```ruby blog_post_locales = environment.locales.all ``` Retrieving one locale by ID from the environment: ```ruby blog_post_locale = environment.locales.find(locale_id) ``` Creating a locale: ```ruby environment.locales.create(name: 'German', code: 'de-DE') ``` Creating a locale with fallback: ```ruby environment.locales.create(name: 'German', code: 'de-DE', fallback_code: 'en-US') ``` Updating a locale: ```ruby blog_post_locale.update(name: 'German', code: 'de-DE') ``` Updating a locale with fallback: ```ruby blog_post_locale.update(name: 'German', code: 'de-DE', fallback_code: 'en-US') ``` Destroying a locale: ```ruby blog_post_locale.destroy ``` ### Tags Retrieving all tags from the environment: ```ruby tags = environment.tags.all ``` Retrieving one tag by ID from the environment: ```ruby tag = environment.tags.find(tag_id) ``` Creating a tag: ```ruby environment.tags.create(name: 'tag name', id: 'tagID') ``` Updating a tag: ```ruby tag.update(name: 'new name') ``` Destroying a tag: ```ruby tag.destroy ``` Tagging an entry: ```ruby entry.update(_metadata: {"tags": [{ "sys": { "type": "Link", "linkType": "Tag", "id": "fooTag" } }]}) ``` Tagging an asset: ```ruby asset.update(_metadata: {"tags": [{ "sys": { "type": "Link", "linkType": "Tag", "id": "fooTag" } }]}) ``` ### Roles Retrieving all roles from the space: ```ruby blog_post_roles = blog_space.roles.all ``` Retrieving one role by ID from the space: ```ruby blog_post_role = blog_space.role.find(role_id) ``` Creating a role: ```ruby role_attributes = { name: 'My Role', description: 'foobar role', permissions: { 'ContentDelivery': 'all', 'ContentModel': ['read'], 'Settings': [] }, policies: [ { effect: 'allow', actions: 'all', constraint: { and: [ { equals: [ { doc: 'sys.type' }, 'Entry' ] }, { equals: [ { doc: 'sys.type' }, 'Asset' ] } ] } } ] } blog_space.roles.create(role_attributes) ``` Updating a role: ```ruby blog_post_role.update(name: 'Some Other Role') # Can change any attribute here ``` Destroying a role: ```ruby blog_post_role.destroy ``` ### Webhooks Retrieving all webhooks from the space: ```ruby webhooks = blog_space.webhooks.all ``` Retrieving one webhook by ID from the space: ```ruby blog_post_webhook = blog_space.webhooks.find(webhook_id) ``` Creating a webhook: ```ruby blog_space.webhooks.create( name: 'My Webhook', url: 'https://www.example.com', httpBasicUsername: 'username', httpBasicPassword: 'password' ) ``` Updating a webhook: ```ruby blog_post_webhook.update(url: 'https://www.newlink.com') ``` Destroying a webhook: ```ruby blog_post_webhook.destroy ``` Creating a webhook with custom headers and custom topics: ```ruby blog_space.webhooks.create( name: 'Entry Save Only', url: 'https://www.example.com', topics: [ 'Entry.save' ], headers: [ { key: 'X-My-Custom-Header', value: 'Some Value' } ] ) ``` #### Webhook Calls Retrieving all webhook call details from a webhook: ```ruby all_call_details = my_webhook.webhook_calls.all ``` Retrieving one webhook call detail by ID from a webhook: ```ruby call_details = my_webhook.webhook_calls.find(call_id) ``` #### Webhook Health Retrieving webhook health details from a webhook: ```ruby health_details = my_webhook.webhook_health.find ``` ### Space Memberships Retrieving all space memberships from the space: ```ruby memberships = blog_space.space_memberships.all ``` Retrieving one space membership by ID from the space: ```ruby blog_post_membership = blog_space.space_memberships.find(membership_id) ``` Creating a space membership: ```ruby blog_space.space_memberships.create( admin: false, roles: [ { 'sys' => { 'type' => 'Link', 'linkType' => 'Role', 'id' => 'my_role_id' } } ], email: 'foobar@example.com' ) ``` Updating a space membership: ```ruby blog_post_membership.update(admin: true) ``` Destroying a space membership: ```ruby blog_post_membership.destroy ``` ### Organizations Retrieving all organization details: ```ruby organizations = client.organizations.all ``` ### Usage *Note*: This feature is available only to Commited v2 customers. #### Organization Periodic Usage Retrieving all API Usage statistics for an Organization during a given usage period, broken down by organization for all APIs: ```ruby # Optionally, you can pass the metric, start and end date filters usage = client.organization_periodic_usages('organization_id').all # For example only CDA and CMA metrics from yesterday onwards usage = client.organization_periodic_usages('organization_id').all('metric[in]': ['cda', 'cma'], startDate: (Date.today - 1).iso8601) ``` Alternatively, if you have an already fetched organization: ```ruby # Breaking down CMA usage by space, for a given period. usage = organization.periodic_usages.all ``` #### Space Periodic Usage Retrieving all API Usage statistics for an Organization during a given usage period, broken down by space for all APIs: ```ruby # Optionally, you can pass the metric, start and end date filters usage = client.space_periodic_usages('organization_id').all # For example only CDA and CMA metrics from yesterday onwards usage = client.space_periodic_usages('organization_id').all('metric[in]': ['cda', 'cma'], startDate: (Date.today - 1).iso8601) ``` Alternatively, if you have an already fetched organization: ```ruby # Breaking down CMA usage by space, for a given period. usage = organization.space_periodic_usages.all ``` ### Users Retrieving current user details: ```ruby user = client.users.me ``` Retrieving all users in organization: ```ruby user = organization.users.all ``` Retrieving one user by ID from an organization: ```ruby user = organization.users.find('user_id') ``` Retrieving all users in a space: ```ruby user = blog_space.users.all ``` Retrieving one user by ID from the space: ```ruby user = blog_space.users.find('user_id') ``` ### UI Extensions Retrieving all UI extensions from the environment: ```ruby extensions = environment.ui_extensions.all ``` Retrieving one UI extension by ID from the environment: ```ruby blog_post_extension = environment.ui_extensions.find(extension_id) ``` Creating a UI extension: ```ruby environment.ui_extensions.create( extension: { 'name' => 'My extension', 'src' => 'https://www.example.com', 'fieldTypes' => [{"type": "Symbol"}], 'sidebar' => false } ) ``` Destroying a UI extension: ```ruby blog_post_extension.destroy ``` ### API Keys Retrieving all API keys from the space: ```ruby blog_post_api_keys = blog_space.api_keys.all ``` Retrieving one API key by ID from the space: ```ruby blog_post_api_key = blog_space.api_keys.find(api_key_id) ``` Creating an API key: ```ruby blog_space.api_keys.create(name: 'foobar key', description: 'key for foobar mobile app') ``` Creating an API key with multiple environments: ```ruby blog_space.api_keys.create( name: 'foobar key - multiple environments', description: 'key for foobar app', environments: [ { sys: { type: 'Link', linkType: 'Environment', id: 'master' } }, { sys: { type: 'Link', linkType: 'Environment', id: 'staging' } } ] ) ``` ### Preview API Keys Retrieving all Preview API keys from the space: ```ruby blog_post_preview_api_keys = blog_space.preview_api_keys.all ``` Retrieving one Preview API key by ID from the space: ```ruby blog_post_preview_api_key = blog_space.preview_api_keys.find(api_key_id) ``` If you already have an API key fetched, you can retrieve the Preview API key from it: ```ruby blog_post_preview_api_key = blog_post_api_key.preview_api_key ``` ### Personal Access Tokens Retrieving all personal access tokens: ```ruby tokens = client.personal_access_tokens.all ``` Retrieving one personal access token by ID: ```ruby token = client.personal_access_tokens.find(token_id) ``` Creating a personal access token: ```ruby client.personal_access_tokens.create(name: 'foobar key', scopes: ['content_management_manage']) ``` Revoking a personal access token: ```ruby token.revoke ``` ### Editor Interface Retrieving editor interface for a content type: ```ruby blog_post_editor_interface = blog_post_content_type.editor_interface.default ``` You can call the EditorInterface API from any level within the content model hierarchy, take into account that you'll need to pass the IDs of the levels below it. > Hierarchy is as follows: > `No Object -> Environment -> ContentType -> EditorInterface` ### Entry Snapshots Retrieving all snapshots for a given entry: ```ruby snapshots = entry.snapshots.all ``` Retrieving a snapshot for a given entry: ```ruby snapshot = entry.snapshots.find('some_snapshot_id') ``` ### Entry references Retrieving entry references: ```ruby references = entry.references(include: 1) ``` ### Content Type Snapshots Retrieving all snapshots for a given content type: ```ruby snapshots = content_type.snapshots.all ``` Retrieving a snapshot for a given content type: ```ruby snapshot = content_type.snapshots.find('some_snapshot_id') ``` ### Pagination ```ruby environment.entries.all(limit: 5).next_page environment.assets.all(limit: 5).next_page environment.entries.all(limit: 5).next_page ``` ### Logging Logging is disabled by default, it can be enabled by setting a logger instance and a logging severity. ```ruby client = Contentful::Management::Client.new('access_token', logger: logger_instance, log_level: Logger::DEBUG) ``` Example loggers: ```ruby 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. ### Raise Errors 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. ```ruby client = Contentful::Management::Client.new('access_token', raise_errors: true) ``` ### Content Type Cache This allows for fetching content types for your environment at client instantiation time, which prevents extra requests per entry. To enable this, in your client instantiation do: ```ruby client = Contentful::Management::Client.new(token, dynamic_entries: {'my_space_id' => 'my_environment_id'}) ``` You can enable the cache for as many environments as you want. If no environment is added, content types will be fetched upon environment find. To completely disable this feature, upon client instantiation do: ```ruby client = Contentful::Management::Client.new(token, disable_content_type_caching: true) ``` ### Proxy Support This allows for using the CMA SDK through a proxy, for this, your proxy must support HTTPS and your server must have a valid signed certificate. To enable this, in your client instantiation do: ```ruby PROXY_HOST = 'localhost' PROXY_PORT = 8888 # Just host/port client = Contributing::Management::Client.new( token, proxy_host: PROXY_HOST, proxy_port: PROXY_PORT ) # With username/password client = Contributing::Management::Client.new( token, proxy_host: PROXY_HOST, proxy_port: PROXY_PORT, proxy_username: 'YOUR_USERNAME', proxy_password: 'YOUR_PASSWORD' ) ``` # Rate limit management With the following configuration options you can handle how rate limits are handled within your applications. ## :max_rate_limit_retries To increase or decrease the retry attempts after a 429 Rate Limit error. Default value is 1. Using 0 will disable retry behaviour. Each retry will be attempted after the value (in seconds) of the `X-Contentful-RateLimit-Reset` header, which contains the amount of seconds until the next non rate limited request is available, has passed. This is blocking per execution thread. ## :max_rate_limit_wait Maximum time to wait for next available request (in seconds). Default value is 60 seconds. Keep in mind that if you hit the houly rate limit maximum, you can have up to 60 minutes of blocked requests. It is set to a default of 60 seconds in order to avoid blocking processes for too long, as rate limit retry behaviour is blocking per execution thread. ## Contributing 1. Fork it ( https://github.com/[my-github-username]/contentful-management/fork ) 2. Create your feature branch (`git checkout -b my-new-feature`) 3. Commit your changes (`git commit -am 'Add some feature'`) 4. Push to the branch (`git push origin my-new-feature`) 5. Create a new Pull Request