Using the Shopify API Console for Ruby

If you’ll be writing your app in Rails, or want to troubleshoot issues in your app, the Shopify API Console for Ruby — a thin wrapper around our Shopify API Ruby gem — will allow you to easily interact with the Admin API directly from your terminal, without running a full Rails app or making HTTP requests via curl.

This tutorial will get you started using the Shopify API console in development.

Prerequisites

Before you begin using the console, you will need a few things:

Setup your development store and get the required gems

To become a Shopify Partner, sign up for a free Shopify Partner account.

As a Shopify Partner, you gain access to the Partner Dashboard, where you can create development stores. To create a development store, navigate to the “Stores” tab and click Add store.

Open up your development store and populate it with Orders, Customers, Products, etc. — whatever you may need to properly develop your app.

To generate a private API key, go to your development store and click on the Apps tab. At the bottom of the screen, click on the Manage private apps link.

Once you have your API key, install the Shopify API and Shopify API Console Ruby gems.

$ gem install shopify_api shopify_api_console

Use the console

Open up your terminal, and type shopify-api.

$ shopify-api
Commands:
  shopify-api add CONNECTION        # create a config file for a connection named...
  shopify-api console [CONNECTION]  # start an API console for CONNECTION
  shopify-api default [CONNECTION]  # show the default connection, or make CONNEC...
  shopify-api edit [CONNECTION]     # open the config file for CONNECTION with yo...
  shopify-api help [COMMAND]        # Describe available commands or one specific...
  shopify-api list                  # list available connections
  shopify-api remove CONNECTION     # remove the config file for CONNECTION
  shopify-api show [CONNECTION]     # output the location and contents of the CON...

You’re presented with options for setting up and managing connection configuration. Nothing is set up yet, so start by adding a connection. Name it whatever you like, but make sure that the URL matches up with that of your development store. You’ll be prompted to enter in your API key and password. Be sure to enter the API password, not secret.

$ shopify-api add myshopifystore
Domain? (leave blank for myshopifystore.myshopify.com) myshopifystore.myshopify.com
open https://myshopifystore.myshopify.com/admin/apps/private in your browser to get API credentials
API key? [REDACTED]
Password? [REDACTED]
create  .shopify/shops/myshopifystore.yml
remove  .shopify/shops/default
Default connection is myshopifystore

Now, start the console. Type shopify-api console:

$ shopify-api console
using myshopifystore.myshopify.com

To make things easier, you can include the ShopifyAPI module provided by the Shopify API gem right away. This is optional, but if you leave it off, you’ll need to prefix API calls with ShopifyAPI::.

> include ShopifyAPI

Now you can start to query the API and look at data from your store. Check out the API docs to see what is queryable and mutable.

To get a list of products, type Product.all:

> Product.all

Try mutating some data; add a customer with the following values:

{
  first_name: 'Firstname',
  last_name: 'Lastname',
  email: 'firstname.lastname@shopify.com',
  addresses: [
    {
      address1: '123 Fake St',
      city: 'Townsville',
      province: 'ON',
      phone: '555-1212',
      zip: '123ABC',
      last_name: 'Lastname',
      first_name: 'Firstname',
      country: 'CA'
    }
  ],
  send_email_invite: true
}
> i = ShopifyAPI::Customer.new({first_name: 'Firstname', last_name: 'Lastname', email: 'firstname.lastname@shopify.com', addresses: [{ address1: '123 Fake St', city: 'Townsville',  province: 'ON', phone: '555-1212', zip: '123ABC', last_name: 'Lastname', first_name: 'Firstname', country: 'CA' }], send_email_invite: true })
> i.save
 => true

Don’t forget to save the entry!

You’ve now successfully added a customer to your dev store, and sent them an email invitation.

Troubleshoot errors

By making a small change to the previous example, you can see how to troubleshoot errors. Change the entry slightly to set a password instead of sending an email invite, and then save the entry.

{
  first_name: 'Firstname',
  last_name: 'Lastname',
  email: 'firstname.lastname@shopify.com',
  addresses: [
    {
      address1: '123 Fake St',
      city: 'Townsville',
      province: 'ON',
      phone: '555-1212',
      zip: '123ABC',
      last_name: 'Lastname',
      first_name: 'Firstname',
      country: 'CA'
    }
  ],
  password: '1234',
  password_confirmation: '1234'
}

Trying to save this data fails:

> i.save
 => false

Type i.errors to find out why. You’ll get some information back on what you tried to POST, and some information on the error:

@remote_errors=#<ActiveResource::ResourceInvalid: Failed.  Response code = 422.  Response message = Unprocessable Entity.>, @validation_context=nil, @errors=#<ActiveResource::Errors:0x007fc814173b60 ...>>, @messages={:password=>["is too short (minimum is 5 characters)"], :email=>["has already been taken"]

It didn’t work because the password is too short, and the email address is already registered to the first customer you created. You’ve just quickly and easily debugged why an API call wasn’t working!

Make complex calls

Get a list of resources using query parameters

Find all of a given resource type (e.g. Products, Customers, etc.), using the limit parameter to limit the results:

> Product.find(:all, :params => {:limit => 3})

Update a resource

Add a description to an existing resource:

> i = CustomCollection.find(7724148)
 => #<ShopifyAPI::CustomCollection:0x007fd47c57acf8 @attributes={"body_html"=>nil, "handle"=>"frontpage", "id"=>7724148, "published_at"=>2012-07-06 17:57:28 UTC, "sort_order"=>"alpha-asc", "template_suffix"=>nil, "title"=>"Frontpage", "updated_at"=>2013-01-31 21:55:21 UTC}, @prefix_options={}>
> i.body_html = 'Give the collection a new description'
 => "Give the collection a new description"
> i.save
 => true
> CustomCollection.find(7724148)
 => #<ShopifyAPI::CustomCollection:0x007fd47c5f1ba0 @attributes={"body_html"=>"Give the collection a new description", "handle"=>"frontpage", "id"=>7724148, "published_at"=>2012-07-06 17:57:28 UTC, "sort_order"=>"alpha-asc", "template_suffix"=>nil, "title"=>"Frontpage", "updated_at"=>2013-02-26 04:21:41 UTC}, @prefix_options={}>

Sign up for a Partner account to get started.

Sign up