MerchantTribe API V1

Version 1 of the MerchantTribe API is a REST based interface that allows for creating, editing, updating and deleting information from a MerchantTribe store. A .NET class library is available that wraps the REST calls in a developer friendly package.

REST Based API

A REST (Representational State Transfer) API is one that uses standard HTTP methods to send and receive information to specific URLs which represent resources. Whenever you request a web page (i.e. www.google.com) you are making an HTTP GET request to the resource www.google.com. Similarly, you can use the MerchantTribe API directly from your browser by making an HTTP GET request for a specific item. Example 1 shows a URL that would request a list of all categories from a MerchantTribe store located at http://localhost and with an API Key for "MySecretKey"

EXAMPLE 1:

http://localhost/api/rest/v1/categories/1234?key=MySecretKey

There are three main HTTP methods (or verbs) that are used by the API. GET, POST, DELETE. Another HTTP method called PUT is common in many REST based APIs but is not used in the V1 API for MerchantTribe.

  • GET used to ask for information
  • POST used to create and update items
  • DELETE used to remove items

API Keys

Version 1 of the API used keys (or tokens) to restrict access to functionality. As a developer, you need to create or obtain an API key in order to make any requests. If you are a store administrator you can log into the admin side, go to Options->Api, and click the "Create New API Key" button. You can remove an existing API key by clicking the "Revoke" link next to the key. You can have more than one API key active at any time. If more than one program or developer will be accessing the API you should strongly consider creating separate keys so that you can easily revoke access for any one program or person.

The API key is passed with every request as either a querystring or post parameter called key. For GET requests, simply append ?key=MyApiKey to the end of the URL where MyApiKey is replaced with your actual key. For POST and DELETE requests a posted value is used instead of a querystring value.

Available Items and URL Structure

Resource URLs are designed to closely map to the actual items from MerchantTribe. For more information on specific URLs and wrapper commands see the API Reference Guide. A list of items available in the API is shown below:

  • Categories
  • Products
  • Price Groups
  • Customer Accounts
  • Affiliates
  • Affiliate Referrals
  • Tax Schedules
  • Taxes
  • Vendors
  • Manufacturers
  • Product Types
  • Product Properties
  • Product Options
  • Product Relationships
  • Images
  • Product Files
  • Product Inventory
  • Volume Discounts
  • Product Reviews
  • Product Category Associations
  • Search Manager
  • Orders
  • Order Transactions
  • Wish List Items
  • Utilities

Request Format (JSON)

Information is sent and received in JSON format only. Responses from the API come wrapped in an APIResponse class. This API response contains a list of ApiErrors (if any) and a Content object which contains the results of the request. Requests are sent by either creating JSON manually or by taking one of the DTO (Data Transfer Object) classes from the .NET helper library and serializing it to JSON.

namespace MerchantTribe.CommerceDTO.v1
{    
    [DataContract]
    public class ApiResponse: IApiResponse
    {
        [DataMember]
        public List Errors { get; set; }

        [DataMember]
        public T Content { get; set; }

        public ApiResponse()
        {
            Errors = new List();
        }
    }
}

ApiErrors contain an error code and description of the problem. The ApiResponse class holds zero or more ApiErrors. Make sure you check the count of errors from all API calls to make sure the request succeeded.