Something is missing in this page?
Chat with us, submit an issue or propose a change on Github!

Ruby client

We released a Ruby gem to make it easy to programmatically read/create/edit/destroy DatoCMS records. Add this line to your application's Gemfile and then install the gem running bundle install within your terminal:

gem "dato"

The first step is to require the DatoCMS gem, and initialize the client with the read-write API token you can find under the Admin area > API tokens section. Let's create an import.rb file with the following content:

require "dato"

# create a DatoCMS client
client = Dato::Site::Client.new("YOUR_API_READWRITE_TOKEN")

Now, suppose we have an administrative area with an Article model, and we want to import a list of articles ie. from a JSON file:

foo

The first thing to know is the ID of the model itself. Let's add the following line to pretty print the existing models:

require "dato"
require "pp"

# create a DatoCMS client
client = Dato::Site::Client.new("YOUR_API_READWRITE_TOKEN")

# inspect the list of models
pp client.item_types.all

Due to historical reasons and backward compatibility, the API exposes some different naming compared to the rest of the product: Models are called Item Types, while Records are called Items. Keep that in mind! Executing the script the following output appears:

$ ruby import.rb
[
  {
    "id"             => "7149",
    "name"           => "Article",
    "singleton"      => false,
    "sortable"       => false,
    "api_key"        => "article",
    "fields"         => ["27669", "27667", "27668"],
    "singleton_item" => nil
  }
]

We can also inspect the fields contained in the model:

# obtain all the fields of the model
pp client.fields.all("7149")

# Output:
#
# [
#   {
#     "id"          => "27667",
#     "label"       => "Title",
#     "field_type"  => "string",
#     "api_key"     => "title",
#     "hint"        => nil,
#     "localized"   => false,
#     "validators"  => {},
#     "position"    => 2,
#     "appeareance" => {"type"=>"title"},
#     "item_type"   => "7149"
#   },
#   {
#     "id"          => "27668",
#     "label"       => "Content",
#     "field_type"  => "text",
#     "api_key"     => "content",
#     "hint"        => nil,
#     "localized"   => false,
#     "validators"  => {},
#     "position"    => 3,
#     "appeareance" => {"type"=>"wysiwyg"},
#     "item_type"   => "7149"
#   },
#   {
#     "id"          => "27669",
#     "label"       => "Cover image",
#     "field_type"  => "image",
#     "api_key"     => "cover_image",
#     "hint"        => nil,
#     "localized"   => false,
#     "validators"  => {},
#     "position"    => 1,
#     "appeareance" => {},
#     "item_type"   => "7149"
#   }
# ]

Great, here there are our three fields. Let's create a new article:

# create a new Article record
pp client.items.create(
  item_type: "7149",
  title: "My first article!",
  content: "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed eiusmod.",
  cover_image: client.upload_image("http://i.giphy.com/NXOF5rlaSXdAc.gif")
)

# Output:
# {
#  "id"          => "43846",
#  "updated_at"  => "2017-03-20T13:25:11.707Z",
#  "is_valid"    => true,
#  "title"       => "My first article!",
#  "content"     => "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed eiusmod.",
#  "cover_image" => {
#    "path"   => "/932/1490016285-nxof5rlasxdac-gif",
#    "width"  => 432,
#    "height" => 250,
#    "format" => "gif",
#    "size"   => 5475424,
#    "alt"    => nil,
#    "title"  => nil
#  },
#  "item_type"=>"7149"
# }

As you can see, we use the helper method client.upload_image to pass DatoCMS the image to upload.

Note: ensure that the URL passed passed to client.upload_image is escaped correctly:

require "uri"

escaped = URI.escape(url)
client.upload_image(escaped)

Retrieving records

To retrieve the stored records:

records = client.items.all

If you want to retrieve just the records of a specific model (ie. article):

records = client.items.all("filter[type]" => "article")

You can also pass the model ID instead of the model API identifier.

Linking records

If you have a record with some a link field (ie. an article linked to its category), during the creation you need to pass the ID of the linked record:

category = client.items.create(
  item_type: "7150"
  name: "My category"
)

article = client.items.create(
  item_type: "7149",
  title: "My first article!",
  content: "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed eiusmod.",
)

If you have a "multiple links" field, then you need to pass the array of IDs:

category = client.items.create(
  item_type: "7150"
  name: "My category"
)

article = client.items.create(
  item_type: "7149",
  title: "My first article!",
  content: "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed eiusmod.",
  categories: [ category.id ]
)

Multi-language fields

If localization is enabled on some field, the format of the payload changes a little bit, as you need to pass an hash representing the value of the field for each of the locales you setup in your administrative area:

# create a new Article record
pp client.items.create(
  item_type: "7149",
  title: {
    en: "My first article!",
    it: "Il mio primo articolo!"
  },
  content: "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed eiusmod.",
  cover_image: client.upload_image("http://i.giphy.com/NXOF5rlaSXdAc.gif")
)