Using the API console

If you'll be writing your app in Rails, or want to troubleshoot issues in your app, the haravan API console will allow you to easily interact with the API without running a full Rails app or making HTTP requests via curl.

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

Prerequisites

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

Setup your dev shop and get the haravan_api gem

To become a haravan Partner register here for your free haravan Partner account. As a haravan Partner, you gain access to the Partners dashboard where you can create Dev Shops. To create a Dev Shop, navigate to the "Dev Shops" tab and click Create a new Dev Shop.

Open up your dev shop and popuate it with Orders, Customers, Products, etc. — whatever you may need to properly develop your app.

You can generate your API key one of two ways:

  • Create a private API key: In your dev shop, click on the Apps tab. At the bottom of the screen, click on the Private API key link.
  • Create a public API key: In your Partners dashboard, click on the Apps tab. Click the Create app button and complete the required form. Once you complete the form, you will be given an API key.

Once you have your API key get the haravan_api Ruby gem. The haravan console is included in this gem, so to get started, get it here and follow the installation instructions. Once you're done, we can get going with the console.

Use the console

Open up your terminal, and type 'haravan'

Bobs-MacBook:~ Bob$ 'haravan'
Commands:
  haravan add CONNECTION        # create a config file for a connection named...
  haravan console [CONNECTION]  # start an API console for CONNECTION
  haravan default [CONNECTION]  # show the default connection, or make CONNEC...
  haravan edit [CONNECTION]     # open the config file for CONNECTION with yo...
  haravan help [COMMAND]        # Describe available commands or one specific...
  haravan list                  # list available connections
  haravan remove CONNECTION     # remove the config file for CONNECTION
  haravan 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 add a connection. Name it whatever you like, but make sure that the URL matches up with that of your dev shop. You'll be prompted to enter in your API key and password, which you can find in your shop admin. Be sure to enter the API password, not secret.

Bobs-MacBook:~ Bob$ haravan add ferryorncarroll
Domain? (leave blank for ferryorncarroll.myharavan.com) ferry-orn-and-carroll7638.myharavan.com
open https://ferry-orn-and-carroll7638.myharavan.com/admin/api in your browser to get API credentials
API key? [REDACTED]
Password? [REDACTED]
create  .haravan/shops/ferryorncarroll.yml
remove  .haravan/shops/default
Default connection is ferryorncarroll

That wasn't difficult! Now let's start the console. Type 'haravan console'

Bobs-MacBook:~ Bob$ haravan console using ferryorncarroll.myharavan.com

To make things easier, we'll include the haravanAPI module provided by the haravan_api gem right away. This is optional, but if you leave it off, you'll need to prefix API calls with 'haravanAPI::'.

Bobs-MacBook:~ Bob$ haravan console
using ferryorncarroll.myharavan.com
1.9.3p125 :001 > include haravanAPI
 => Object
1.9.3p125 :002 >

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

Let's start out with something simple. To look at your products, type 'Product.all'

1.9.3p125 :002 > Product.all

Let's try something more advanced. We're going to add a customer with the following values:

 {
    'first_name'=>'Steve',
    'last_name'=>'Lastnameson',
    'email'=>'steve@email.com',
    'addresses'=>[
        {
            'address1'=>'123 Oak St',
            'city'=>'Ottawa',
            'province'=>'ON',
            'phone'=>'555-1212',
            'zip'=>'123ABC',
            'last_name'=>'Lastnameson',
            'first_name'=>'Mother',
            'country'=>'CA'
        }
    ],
    'send_email_invite'=>true
}
1.9.3p125 :036 > i = haravanAPI::Customer.new({'first_name' => 'Steve','last_name' => 'Lastnameson','email' => 'steve@email.com','addresses' => [{'address1' => '123 Oak St','city' =>'Ottawa', 'province'=>'ON', 'phone'=>'555-1212', 'zip'=>'123ABC', 'last_name'=>'Lastnameson', 'first_name'=>'Mother', 'country'=>'CA' } ], 'send_email_invite'=>true})

Don't forget to save the entry!

1.9.3p125 :037 > i.save
 => true

Troubleshoot errors

You've now successfully added a customer to our shop, and sent them an email invitation. Let's use this example to see how we can troubleshoot errors. Change the entry slightly to set a password instead of sending an email invite, and then save the entry.

 {
    'first_name'=>'Steve',
    'last_name'=>'Lastnameson',
    'email'=>'steve@email.com',
    'addresses'=>[
        {
            'address1'=>'123 Oak St',
            'city'=>'Ottawa',
            'province'=>'ON',
            'phone'=>'555-1212',
            'zip'=>'123ABC',
            'last_name'=>'Lastnameson',
            'first_name'=>'Mother',
            'country'=>'CA'
        }
    ],
    'password' => '1234',
    'password_confirmation' => '1234'
}

If we use this data, we'll see that it fails when we try to save.

 1.9.3p125 :035 > i.save
 => false

So, why did it fail? Type 'i.errors' to find out. We'll get some information back on what we tried to post, and some information on the error, which we see is the following.

 @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 we created. We've just quickly and easily troubleshooted why an API call wasn't working. Success!

Make complex calls

Let's take a look at how to string together a couple more complex calls.

Get a list of something using query parameters

Here we'll find all products, using the limit parameter to limit the results to just three products.

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

Update something

Add a description to an existing collection.

 1.9.3p125 :028 >   i = CustomCollection.find(7724148)
 => #<haravanAPI::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={}>
1.9.3p125 :029 > i.body_html = 'Give the collection a new description'
 => "Give the collection a new description"
1.9.3p125 :030 > i.save
 => true
1.9.3p125 :031 > CustomCollection.find(7724148)
 => #<haravanAPI::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={}>

Haravan - Công ty công nghệ cung cấp giải pháp kinh doanh thương mại điện tử, duy nhất tại Việt Nam được Google lựa chọn vào chương trình bệ phóng tiềm năng với hỗ trợ và đào tạo công nghệ để vươn ra thị trường quốc tế vững chắc.