Shopify 07/29/2011

Developing Shopify Apps, Part 2: Exploring the API

In the previous article in this series, we did the following:

  1. Joined Shopify's Partner Program
  2. Created a new test shop
  3. Launched a new test shop
  4. Added an app to the test shop
  5. Played around with a couple of quick API calls through the browser

In this article, we'll take a look at some of the calls that you can make to Shopify's API and how they relate to the various parts of your shop. This will give you an idea of what Shopify shops are like as well as show you to control them programmatically.

My Shop, via the Admin Page

I've set up a test shop called Joey's World O' Stuff for this series of articles. Feel free to visit it at any time. It lives at this URL:

https://nienow-kuhlman-and-gleason1524.myshopify.com/

If you followed along with the last article, you also have a test shop with a similarly URL. Test shop URLs are randomly generated. The shops themselves are meant to be temporary; they're for experimenting with themes, apps and content. We'll work with real shops later in this series, and they'll have URLs that make sense.

If you were to visit the URL for my test shop at the time of this writing, you'd see something like this:


The admin panel for any shop can be accessed by adding /admin to the end of its base URL. If you're not logged into your shop, you'll be sent to the login page. If you're already logged in, you'll be sent to the admin panel's home page, which should look something like this:


I've highlighted the upper right-hand corner of the admin panel home page, where the Preferences menu is. Click on Preferences, then in the menu that pops up, click on General Settings:


You should now see the General Settings page, which should look like this:


The fields on the screen capture of this page are a little small, so I'll list them below:

  • Shop name: Joey's World O' Stuff
  • Email: joey@shopify.com
  • Shop address:
    • Street: 31 Spooner Street
    • Zip: 02903
    • City: Quahog
    • Country: United States
    • State: Rhode Island
    • Phone: (555) 555-5555
  • Order ID formatting: #{{number}}
  • Timezone: (GMT-05:00) Eastern Time (US & Canada)
  • Unit system: Imperial system (Pound, inch)
  • Money formatting: ${{amount}}
  • Checkout language: English

That's the information for my shop as seen through admin panel on the General Settings page. 

Just as the admin panel lets you manually get and alter information about your shop, the Shopify API lets applications do the same thing, programatically. What we just did via the admin panel, we'll now do using the API. But first, let's talk about the API.

Detour: A RESTafarian API


The Shopify API is RESTful, or, as I like to put it, RESTafarian. REST is short for REpresentational State Transfer, and it's an architectural style that also happens to be a simple way to make calls to web services. I don't want to get too bogged down in explaining REST, but I want to make sure that we're all on the same page.

The Shopify API exposes a set of resources, each of which is some part of a shop. Here's a sample of some of the resources that the API lets you access:

  • Shop: The general settings of your shop, which include things like its name, its owner's name, address, contact info and so on.
  • Products: The set of products available through your shop.
  • Images: The set of images of your store's products.
  • Customers: The set of your shop's customers.
  • Orders: The orders placed by your customers.
(If you'd like to see the full list of resources, go check out the API Documentation. They're all listed in a column on the right side of the page.)

To do things with a shop, whether it's to get the name of the shop or the contact email of its owner, get a list of all the products available for sale, or find out which customers are the biggest spenders, you apply verbs to resources like the ones listed above. In the case of RESTful APIs like Shopify's, those verbs are the four verbs of HTTP:

  1. GET: Read the state of a resource and not make any changes to it in the process. When you type an URL into your browser's address bar and press Enter, your browser responds by GETting that page.
  2. POST: Create a new resource (I'm simplifying here quite a bit; POST is the one HTTP verb with a lot of uses). When you fill out and submit a form on a web page, your browser typically uses the POST verb.
  3. PUT: Update an existing resource.
  4. DELETE: Delete an existing resource.

Here's an example of putting resources and verbs together. Suppose you were writing an app that let a shopowner do bulk changes to the products in his or her store. Your app would need to access the Products resource and then apply the four HTTP verbs in these ways:

  • If you wanted to get information about one or more products in a shop, whether it's the list of all the products in the shop, information about a single product, or a count of all the products in the shop, you'd use the GET verb and apply it to the Products resource.
  • If you wanted to add a product to a shop, you'd use the POST verb and apply it to the Products resource.
  • If you wanted to modify an existing product in a shop, you'd use the PUT verb and apply it to the Products resource.
  • If you wanted to delete a product from a shop, you'd use the DELETE verb and apply it to the Products resource.
Keep in mind that not all resources respond to all four verbs. Certain resources like Shop aren't programmatically editable, and as a result, it doesn't respond to PUT.

My Shop, via the API

Let's get the same information that we got from the admin panel's General Settings page, but using the API this time. In order to do this, we need to know two things:

  1. Which resource to access. In this case, it's pretty obvious: the Shop resource.
  2. Which verb to use. Once again, it's quite clear: GET. (Actually, if you check the API docs, it's very clear; it's the only verb that the Shop resource responds to.) 

The nice thing about GET calls to web APIs is that you can try them out very easily: just type them into your browser's address bar!

You specify a resource with its URL (or more accurately, URI). That's what the the "R" in URL and URI stand for: resource. To access a Shopify resource, you need to form its URI using this general format:

api-key:password@shop-url/admin/resource-name.resource-type

Where:

  • api-key is the API key for your app (when you create an app, Shopify's back end generates a unique API key for it)
  • password is the password for your app (when you create an app, Shopify's back end generates a password for it)
  • shop-url is the URL for your shop
  • resource-name is the name of the resource
  • resource-type is the type of the resource; this is typically either xml if you'd like the response to be given to your app in XML format or json is you'd like the response to be in JSON.

You can find the API key and password for your app on the Shopify API page of your shop's admin panel. You can get there via this URL:

shop-url/admin/api

where shop-url is your shop's URL. You can also get there by clicking on the Apps menu, which is located near the upper right-hand corner of every page in the admin panel and selecting Manage Apps:


You'll see a list of sets of credentials, one set for each app. Each one looks like this:


You can copy the API key and password for your app from this box. Better yet, you can copy the example URL, shown below, and then edit it to create the API call you need:


The easiest way to get general information about your shop is to:

  1. Copy the example URL
  2. Paste it into your browser's address bar
  3. Edit the URL, changing orders.xml to shop.xml
  4. Press Enter

You should see a result that looks something like this:

<shop>
  <name>Joey's World O' Stuff</name>
  <city>Quahog</city>
  <address1>31 Spooner Street</address1>
  <zip>02903</zip>
  <created-at type="datetime">2011-07-22T14:43:21-04:00</created-at>
  <public type="boolean">false</public>
  <country>US</country>
  <domain>nienow-kuhlman-and-gleason1524.myshopify.com</domain>
  <id type="integer">937792</id>
  <phone>(555) 555-5555</phone>
  <source nil="true"/>
  <province>Rhode Island</province>
  <email>joey@shopify.com</email>
  <currency>USD</currency>
  <timezone>(GMT-05:00) Eastern Time (US & Canada)</timezone>
  <shop-owner>development shop</shop-owner>
  <money-format>${{amount}}</money-format>
  <money-with-currency-format>${{amount}} USD</money-with-currency-format>
  <taxes-included type="boolean">false</taxes-included>
  <tax-shipping nil="true"/>
  <plan-name>development</plan-name>
</shop>

Note that what you get back is a little more information than what you see on the admin panel's General Settings page; you also get some information that you'd find on other admin panel pages, such as the currency your shop uses and how taxes are applied to your products' and shipping prices.

You can also get your shop information in JSON by simply changing the last part of the URL from shop.xml to shop.json. You'll see a result like this:

{"shop":
  {"address1":"31 Spooner Street",
   "city":"Quahog",
   "name":"Joey's World O' Stuff",
   "plan_name":"development",
   "shop_owner":"development shop",
   "created_at":"2011-07-22T14:43:21-04:00",
   "zip":"02903",
   "money_with_currency_format":"${{amount}} USD",
   "money_format":"${{amount}}",
   "country":"US",
   "public":false,
   "taxes_included":false,
   "domain":"nienow-kuhlman-and-gleason1524.myshopify.com",
   "id":937792,
   "timezone":"(GMT-05:00) Eastern Time (US \u0026 Canada)",
   "tax_shipping":null,
   "phone":"(555) 555-5555",
   "currency":"USD",
   "province":"Rhode Island",
   "source":null,
   "email":"joey@shopify.com"}
}

(Okay, I formatted this one so it would be easy to read. It was originally one long line; easy for computers to read, but not as easy for humans.)

Other Things in My Shop, via the API


If you followed my steps from the previous article in this series, your shop should have a small number of predefined products in your store. You can look at all the shop's products by taking the URL you just used and changing the last part of the URL to products.xml.

Here's a shortened version of the output I got:

<products type="array">
  <product>
    <product-type>Shirts</product-type>
    <handle>multi-channelled-executive-knowledge-user</handle>
    <created-at type="datetime">2011-07-22T14:43:24-04:00</created-at>
    <body-html>
      ...really long description here...
    </body-html>
    <title>Multi-channelled executive knowledge user</title>
    <template-suffix nil="true"/>
    <updated-at type="datetime">2011-07-22T14:43:24-04:00</updated-at>
    <id type="integer">47015882</id>
    <vendor>Shopify</vendor>
    <published-at type="datetime">2011-07-22T14:43:24-04:00</published-at>
    <tags>Demo, T-Shirt</tags>
    <variants type="array">
      <variant>
        <price type="decimal">19.0</price>
        <position type="integer">1</position>
        <created-at type="datetime">2011-07-22T14:43:24-04:00</created-at>
        <title>Medium</title>
        <requires-shipping type="boolean">true</requires-shipping>
        <updated-at type="datetime">2011-07-22T14:43:24-04:00</updated-at>
        <inventory-policy>deny</inventory-policy>
        <compare-at-price type="decimal" nil="true"/>
        <inventory-management nil="true"/>
        <taxable type="boolean">true</taxable>
        <id type="integer">110148372</id>
        <grams type="integer">0</grams>
        <sku/>
        <option1>Medium</option1>
        <option2 nil="true"/>
        <fulfillment-service>manual</fulfillment-service>
        <option3 nil="true"/>
        <inventory-quantity type="integer">5</inventory-quantity>
      </variant>
    </variants>
    <images type="array"/>
    <options type="array">
    <option>
    <name>Title</name>
    </option>
    </options>
  </product>
  ...
  (more products here)
  ...
</products>

If you want this information in JSON format, all you need to do is change the URL so that it ends with .json instead of .xml.

Try Out the Other Resources

There are a number of Shopify API resources that you can try out -- try out some GET calls on these:

  • articles.xml and articles.json
  • assets.xml or assets.json
  • blogs.xml or blocks.json
  • comments.xml or comments.json
  • customers.xml or customers.json

There are more resources that you can access through GET; the Shopify Wiki lists them all in the right-hand column. Try them out!

Next: Graduating to a real store, and trying out the POST, PUT and DELETE verbs.

[ This article also appears in Global Nerdy. ]