Introducing Getsy, A Secure Command Line Interface to the Etsy API

Posted by on January 10, 2011

Some of the most productive tools out there come from the command line and so when you’re testing REST-based requests it makes a lot of sense to use the command line tool curl. But since the OAuth protocol uses 3-legged authentication, and there are several tokens and other intricacies to handle, it makes curl very difficult to use directly. As I was working on the Etsy API last year I found it would be useful to have something similar to curl that I could quickly make API requests with using OAuth in both the sandbox and production environments. WWW::Getsy is a command line tool that does just that.

This is an introduction to the tool that shows how to get it setup and start making a few calls. The tool is written in modern Perl and I’ll show how to get everything setup quickly and easily without needing to use root privileges.

Perlbrew is a great module that will let you easily switch between multiple versions of Perl. Using it has a couple of advantages over using your system version of Perl. The first is that you can easily install a current version of Perl locally in your home directory. Most distros have a pretty outdated version installed and this will give you a decent version to work with. The second advantage is it will allow you to install your modules locally, without the need for superuser privileges. This way you won’t have to interfere with whats already installed on your system.

So lets grab it and make it executable:

$ curl -LO http://xrl.us/perlbrew
$ chmod +x perlbrew

Run the basic initialization:

$ ./perlbrew install
$ ./perl5/perlbrew/bin/perlbrew init

Get the environment setup by adding this line to your ~/.bashrc file:

$ echo "source ./perl5/perlbrew/etc/bashrc" >> ~/.bashrc
$ source ~/.bashrc

And then run the installation of a current version, in this case 5.12.2. This step can take a bit depending on your machine.

$ perlbrew install perl-5.12.2

Now that its installed switch to that version:

$ perlbrew switch perl-5.12.2

So now you’ll see if you look at the perl version that you’re running our newly installed version:

$ perl --version
This is perl 5, version 12, subversion 2 (v5.12.2) built for i686-linux

Now you’re ready to install the WWW::Getsy module, which you can do in one step with this command (note it will take a bit to get all of the dependencies, but should install cleanly)

$ PERL_MM_USE_DEFAULT=1 cpan WWW::Getsy

While thats installing, if you haven’t already, go ahead and register for a developer account. The confirmation email you receive from that will guide you to get an API key, which should direct you to the app registration form. It will require at a minimum an application name, which you can always change later. After submitting the form you should end up with a key and shared secret.

Getsy requires you to assign these keys to some environment variables, so you may want to add this to your ~/.bashrc file and source it like we did above. Just fill in the key and secret that you just received.

export OAUTH_CONSUMER_KEY='yourkey'
export OAUTH_CONSUMER_SECRET='yoursecret'

Now assuming WWW::Getsy finished installing we’re finally ready to make some calls. The simplest call we can make is a GET for the API method list. Since we’re using sandbox keys, we specify the sandbox argument, and the root path:

$ getsy --sandbox --path '/'

Since this is your first time making a call you will receive some instructions to do the OAuth dance and get your access tokens. This is where you are directed to an Etsy page that you can sign in (or accept if you’re already signed in). When you do you will get a verifier that you can paste in. So if the verifier I got after signing into the link it tells me to go to was “7cb1d239” I would paste that and press enter:

Go to http://www.etsy.com/oauth/signin?oauth_token=sometoken&callback=oob
Then enter the verifier token
7cb1d239
<enter>

If you did everything correctly, you should see some JSON output with all of the method calls that you can make with the Etsy API.

You’ll only have to do that once, as the access token and secret are stored in the ~/.getsy_sandbox file. If you want to use another user later just remove that file, and you’ll be prompted to get a different access token. Otherwise the access token and secret can be reused on subsequent calls.

Note that we can take a look at what arguments the getsy command will accept with the –help parameter:

$ getsy --help
Required option missing: path
usage: getsy [-?] [long options...]
        --sandbox
        --debug
        --path
        --params
        --method
        -? --usage --help  Prints this usage information.

The main argument that you’ll always need (in addition to –sandbox until you get a production key) is the –path argument. The –path argument is how you specify the API command, which you can find from the output of the method list we requested above or in the excellent Etsy API Documentation. The –method argument is used to specify the HTTP method, which defaults to GET. And –params is used to specify parameters in JSON format for commands that accept additional parameters, such as POST commands.

So now lets try to make a POST request. A good one is to try to favorite a listing, and we can do that like so:

$ getsy --sandbox --path '/users/__SELF__/favorites/listings/58171578' --method=post

And the response will look something like this:

{
   "params" : {
      "user_id" : "__SELF__",
      "listing_id" : "58171578"
   },
   "count" : 1,
   "type" : "FavoriteListing",
   "results" : [
      {
         "listing_state" : "active",
         "creation_tsz" : 1294628005,
         "create_date" : 1294628005,
         "user_id" : 6591529,
         "state" : "active",
         "listing_id" : 58171578,
         "favorite_listing_id" : 163590951
      }
   ]
}

The path we used above corresponds to the createUserFavoriteListings command. It says the URI should follow this format: /users/:user_id/favorites/listings/:listing_id

Notice how we used __SELF__ in place of the :user_id parameter. The standard token __SELF__ maps to the user ID of the user using your application under OAuth, which is what we signed in with on our first call. For the :listing_id, we just used a standard numeric listing id, which can be found in Etsy URLs, or more programmatically with the findAllListingActive command

We can then use the deleteUserFavoriteListings call to make a DELETE request to remove the listing we just favorited:

$ getsy --sandbox --path '/users/__SELF__/favorites/listings/58171578' --method=delete

And the response will look something like:

{
   "params" : {
      "user_id" : "__SELF__",
      "listing_id" : "58171578"
   },
   "count" : 0,
   "type" : "FavoriteListing",
   "results" : []
}

Now lets try a command where we need to specify some parameters with the –params argument. Creating a payment template is a good example. A payment template is basically a template that is setup to signify to a buyer which kinds of payments you accept as a seller. Note you’ll want to be OAuth’d in as a seller or it won’t work correctly. So for the createPaymentTemplate command we can do something like this:

$ getsy --sandbox --path '/payments/templates' --method=post --params '{"allow_paypal" : "true", "paypal_email" : "test@test.com"}'

Note if you already have a payment template setup for that user, it won’t let you create another one, so you could check what the current payment template id is for that user with the findAllUserPaymentTemplates command:

$ getsy --sandbox --path '/users/__SELF__/payments/templates'

Notice I didn’t specify the –method parameter this time since GET is the default. Now find the payment_template_id in the JSON response and use that to update the payment template. Lets assume that id was 5694812 (it will be different for you), I could then use that to make a PUT request to update the template:

$ getsy --sandbox --path '/payments/templates/5694812' --method=put --params '{"allow_paypal" : "true", "paypal_email" : "test@test.com"}'

So now we’ve been able to make some OAuth requests to the Etsy API using a very simple command line tool. All the difficulties of OAuth are wrapped up behind the scenes, and we are able to make GET, PUT, POST, and DELETE requests for our authenticated user.

Posted by on January 10, 2011
Category: api

7 Comments

That’s sure will be convenient! Thanks for making this available.

Oops, sorry for the grammatical issue.

Installation of perlbrew went okay, as well as the new perl version (that did take forever) and the Getsy module.

I haven’t worked with Perl much, but Looks like you’ll be drawing some of us into its sigilicious world! Of course, that’s not needed but I am unlikely to resist hacking on the scripts a bit. Want to put it on Github, perhaps?

Thanks Julian, you can find it on github here: https://github.com/jgoulah/WWW-Getsy

I received an email newsletter from API (which I hadn’t signed up for). I’m not a web designer, so I’m just wondering, in layman’s terms, what is Getsy for? I’m an Etsy shop owner and am just curious. Thanks! -Teresa

Hi Teresa, Getsy is just a simple interface to our API. API stand for “application programming interface”, and allows external developers to write applications that securely access data (but only when a user grants them access). A protocol called OAuth is used for this, and Justin did a great job describing that here: http://www.etsy.com/storque/etsy-news/handmade-code-how-to-safely-use-apps-that-connect-to-your-et-10360 – Hope that helps!

Would recommend including a “preview” parameter. If you are accepting POST/DELETE requests via command line – command line is begging for typographical errors – it would make sense to enable users to see what the result would look like before they commit to a change. Maybe that’s what the “debug” option does, maybe not.

Also recommend STDIN confirmation on any DELETE method calls.

    I could think about that a bit, do you mean just showing the url and json you are sending in a more readable format, and having a yes/no confirmation? That would be simple enough. Also the code is open source and patches are certainly welcome. It can be found on github here https://github.com/jgoulah/WWW-Getsy