ModularMerchant
Knowledge Base
Shopping Cart Software Online Manual
Introduction to APIs
"Remote Membership Validation (RMV)" API
Location Home > Developer's Guide > APIs

Introduction to APIs

this article last updated: June 12, 2013
Due to inevitable changes that will be made to the shopping cart software over time, the cart's variable and database structure may change from time to time without advanced notice. We will attempt to keep the information in this article up-to-date, but Modular Merchant makes no guarantee as to the accuracy of the information provided in this article. Use this information at your own risk.

 
Introduction to the Modular Merchant API

Modular Merchant Gold (and higher) account plans have access to a suite of APIs that allow a remotely-hosted website to retrieve information about customers, orders, products and subscriptions by using a simple XML web service. Search criteria can be included in API calls, allowing a user to retrieve a particular set of entries from the store's records.
 
Structuring a Data Request

All API queries should following these guidelines:
  1. Requests should be submitted to the APIs URL, located in your online store. An example of the URL of the API that retrieves order data would look something like: http://www.mystore.com/api/get_orders.php.
  2. The request should be submitted as a standard HTTP POST operation, with the post data containing the request XML.
  3. Requests should be structured in valid XML format.
  4. Each API request must contain a valid API Key (found in your System Settings) and Admin-specific API Key (found in the Admin Account Editor).
  5. The query should include the search parameters that are appropriate to that specific request type. (See examples in the tutorials that follow.)
A Sample XML Request
Here is a brief example of what how the XML of a request posted to the get_orders.php API may be structured: (This will be explained in more detail later.)

example xml
<?xml version="1.0" encoding="utf-8"?>
<api_request>
    <admin_sid>123</admin_sid>
    <admin_key>9c1bc3217974b2fd</admin_key>
    <api_key>315423a19ba51d64</api_key>
    <search_type>keyword</search_type>
    <start_result>0</start_result>
    <number_of_results>50</number_of_results>
    <any_vs_all>any</any_vs_all>
    <order_by>orders.id</order_by>
    <asc_vs_desc>DESC</asc_vs_desc>
    <search_rule>
        <search_field>orders.id</search_field>
        <compare_type>*LIKE*</compare_type>
        <search_string>123</search_string>
    </search_rule>
</api_request>
 
urlencode the xml data
The data contained in each XML node must be urlencoded. For example, if you wanted the "compare_type" node to be ">" (greater than):

Wrong: <compare_type>></compare_type>

Correct: <compare_type>%3E</compare_type>

 
The Structure of a Response From the API

The responses sent back from the API will always follow these guidelines:
  1. The response from the API will always be returned in XML format.
  2. The XML response will contain a node titled "response_status". Its value will be either error or success. The application handling the API's response should take the appropriate action based on the returned "response_status".
  3. When a "response_status" of success is returned, the XML response will also include a node titled "data," which will contain the results of the query in XML format.
  4. When a "response_status" of error is returned, the XML response will also include a node titled "error_reason," which will contain an explanation of why the query could not be completed.
Samples of XML Responses
Here is a brief example of the structure of some responses to a request posted to the get_orders.php API: (Again, this will be explained in more detail later.)

failure response
<?xml version="1.0" encoding="UTF-8" ?>
<response>
   <response_status>error</
response_status>
   <error_reason>API Key could not be validated.</
error_reason>
</response>


success response
<?xml version="1.0" encoding="UTF-8" ?>
<response>
   <response_status>success</response_status>
   <data>
      <order_sid>87</order_sid>
      <order_total>123.45</order_total>
      <cid>789</cid>
      <email>example%40email.com</email>
      <create_date>1317074358</create_date>
      ...and so on.
   </data>
</response>
 
Authenticating API calls with Keys

For security reasons, API queries must include a set of "keys," which will be used to authenticate the request. Specifically, each request must include both the store's general API Key, and the SID (System ID) number and API Key for the specific Admin Account submitting the query.

Locating your store's general API Key
Your store's general API Key can be found by following these steps:
  1. Log in to your store's Administration Area at http://login.modularmerchant.com
  2. Once logged, go to [Admin > System Settings].
  3. The account's API Key is listed at the top of the System Settings, in the table named Account Statistics.

Locating an Admin's SID and personal API Key
An Admin's API credentials can be found by following these steps:
  1. Log in to your store's Administration Area at http://login.modularmerchant.com
  2. Once logged, go to [Admin > Search Admin Accounts].
  3. On the Search Admin Accounts page, the Admin's SID number will be listed in the column aptly titled SID.
  4. To obtain the Admin's personal API Key, click the  button to open that account in the Admin Editor.
  5. In the Admin Editor, their personal API Key is located in the field titled Admin's API Key. NOTE: This field starts out blank. You will need to create the Admin's initial API Key by clicking the link below the field and clicking the Save Changes button at the bottom of the page.

 
Sample API query using PHP

Below is a sample of how PHP, using cURL, could be used to post request to the store's API, and then capture the API's response to a variable titled $response.

xml post using php
<?php
$store_url = 'http://www.mystore.com/api/get_orders.php';
$admin_sid = '123';
$admin_key = 'B8lk9AkTANfH4bbGHvOG3HBF9NnbQH';
$api_key = '9c1bc41x15423a1c9be51d621a74b2fd';

$curl_data = '<?xml version="1.0" encoding="utf-8"?>
<xmlrequest>
    <admin_sid>'.urlencode($admin_sid).'</admin_sid>
    <admin_key>'.
urlencode($admin_key).'</admin_key>
    <api_key>'.
urlencode($api_key).'</api_key>
    <search_type>'.
urlencode('keyword').'</search_type>
    <start_result>
'.urlencode('0').'</start_result>
    <number_of_results>
'.urlencode('50').'</number_of_results>
    <any_vs_all>
'.urlencode('any').'</any_vs_all>
    <order_by>
'.urlencode('orders.id').'</order_by>
    <asc_vs_desc>
'.urlencode('DESC').'</asc_vs_desc>
    <search_rule>
        <search_field>
'.urlencode('orders.id').'</search_field>
        <compare_type>
'.urlencode('>').'</compare_type>
        <search_string>
'.urlencode('123').'</search_string>
    </search_rule>
</xmlrequest>';

$ch = curl_init();
if($ch) {
     curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
     curl_setopt($ch, CURLOPT_HEADER, false);
     curl_setopt($ch, CURLOPT_URL, $store_url);
     curl_setopt($ch, CURLOPT_POST, true);
     curl_setopt($ch, CURLOPT_POSTFIELDS, $curl_data);
     $response = curl_exec($ch);
     if($response === false) {
         //error
     }
     curl_close($ch);
}

// To print out the response, uncomment the line below.
//echo($response);


?>

tip
The XML data returned by the API is "url encoded". To improve its legibility, be sure to apply urldecode() or a similar function to it.

reference
The PHP website includes some tutorials on how to turn XML data into an object that PHP can use.


See the "Related Articles" section below for instructions on working with a specific API.

— Last Edited - 06/12/2013 12:37pm PDT
Related Articles
"Get Orders" API

Category: Developer's Guide
Rank and add a comment to this article
Only logged in users may leave comments and rank articles. Log in to have your say!
  Knowledge Base Home

  QuickCode™ Tag Glossary

  Modular Merchant.com Homepage

Not Logged in.
Either Log in or create a User Account.

Other articles in this category...

Introduction to APIs

"Remote Membership Validation (RMV)" API

"Get Orders" API

"Get Customers" API

"Edit Customer" API

"Check Customer" API