Introduction to APIs


	Introduction to APIs
	Last Edited - 06/12/2013 12:37pm PDT
	Category Path - Developer's Guide > APIs

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:

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.
The request should be submitted as a standard HTTP POST operation, with the post data containing the request XML.
Requests should be structured in valid XML format.
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).
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:

The response from the API will always be returned in XML format.
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".
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.
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:

Log in to your store's Administration Area at http://login.modularmerchant.com
Once logged, go to [Admin > System Settings].
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:

Log in to your store's Administration Area at http://login.modularmerchant.com
Once logged, go to [Admin > Search Admin Accounts].
On the Search Admin Accounts page, the Admin's SID number will be listed in the column aptly titled SID.
To obtain the Admin's personal API Key, click the button to open that account in the Admin Editor.
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.