Authentication

Calling the API

You can call the Mashery API using the following URL format:

http://api.mashery.com/v2/json-rpc/[site_id]

or

http://api.sandbox.mashery.com/v2/json-rpc/[site_id]

where [site_id] is your designated Mashery site identifier.  To find out your site id, go to your Mashery Dashboard and look at the bottom of the page for the text "Mashery Site ID."

Mashery API key

The Mashery API requires a known token to be passed as part of the request query string. The token is called apikey. The value of the token is a 24 character alphanumeric string assigned by Mashery.

You can create a new Mashery API token by registering your application. Newly created keys must be approved by mashery before they become active.  When you register we will be notified and will approve your key shortly.

You can review existing API keys under my account.

Signing the API Call

Each request must be signed. Valid signature is determined by examining a sig parameter from the query string of the request. The sig value is calculated by generating an MD5 hash made up of the API key, the API user's shared secret, and a UNIX timestamp reflecting number of seconds since the Unix Epoch (January 1 1970 00:00:00 GMT) at the time the request was made. A five-minute wiggle is permitted on either side of the current timestamp on the Mashery server to allow for reasonable clock drift.

Most programming languages provide an md5()-type of function. The signature should be generated using such a function.

The following is an example of generating a valid signature with PHP:

$apikey = '2fvmer3qbk7f3jnqneg58bu2';  
$secret = 'qvxkmw57pec7';  
$timestamp = gmdate('U'); // 1200603038   
$sig = md5($apikey . $secret . $timestamp);  

An example request to the JSON-RPC interface to the Mashery API, based on a timestamp of 1200603038 (Thu, 17 Jan 2008 20:50:38 +0000), an apikey of 2fvmer3qbk7f3jnqneg58bu2 and a secret of qvxkmw57pec7:

http://api.mashery.com/v2/json-rpc/[site_id]?apikey=2fvmer3qbk7f3jnqneg58bu2&sig=65a08176826fa4621116997e1dd775fa

Permissions

You must have permission in order to make a call into the Mashery API.  This permission is granted to the owner member of the API key.  This owner member must be created within your Mashery Developer Portal and it must be assigned an administration Role.  That role controls which API calls are allowed.

• Administrator
• Program Manager
• Community Manager
• Content Manager
• API Manager
• Portal Manager

To grant API access to a user, grant the corresponding Mashery Dashboard Role.  For example, should you wish to have an apikey that has full access to all capabilities of the Mashery API, create or use a member within your site and grant them the "Administrator" Role.  Consult the documentation for each individual API call for the permissions required to make that call.

Test Call

A test.echo method is provided for testing authentication and signing.  This method takes a single parameter and returns the parameter passed.

Sample PHP Code for calling the test method

/**
 * An example call to the Mashery Api.
 *
 * API documentation is available at
 * http://support.mashery.com/docs/mashery_api/
 */

// Substitute your site id here.  You can find your site id on the Summary tab of the
// administractive dashboard.
$your_site_id = 'replace_me';

// Substitute your key and shared secret.
// You can find this on the My Account page when you log in to support.mashery.com.
$your_apikey = 'replace_me';
$your_shared_secret = 'replace_me';

// Create an instance of an object to make API calls with
$api = new MasheryApi(
    MasheryApi::SANDBOX_ENDPOINT, 
    $your_site_id, 
    $your_apikey, 
    $your_shared_secret);

// Perform a test call
$result = $api->call('test.echo', array('hello'));

// Output the results
print_r($result);

/**
 * A class to call the Mashery API using the curl extension.
 */
class MasheryApi {

    const SANDBOX_ENDPOINT = 'api.sandbox.mashery.com';
    
    const PRODUCTION_ENDPOINT = 'api.mashery.com';

    protected $host;
    
    protected $apikey;
    
    protected $secret;
    
    protected $site_id;
    
    /**
     * Record necessary configuration values
     */
    function __construct($host, $site_id, $apikey, $secret)
    {
        $this->host = $host;
        $this->site_id = $site_id;
        $this->apikey = $apikey;
        $this->secret = $secret;
    }
    
    /**
     * Return the url of the API endpoint to call
     */
    function getEndpointUrl() 
    {
        // The path identifies the site
        $path = 'v2/json-rpc/' . $this->site_id;

        // Authentication and signing are handled in query parameters
        $auth = array();
        $auth['apikey'] = $this->apikey;
        $auth['sig'] = md5($this->apikey . $this->secret . gmdate('U'));
        $query = http_build_query($auth);
        
        // The host identifies which environment to call
        $host = $this->host;
        
        return 'http://' . $host . '/' . $path . '?' . $query;
    }

    /**
     * Perform an HTTP POST
     */
    function httpPost($url, $post_body) 
    {
        $ch = curl_init();
        
        // CUSTOMREQUEST used to bypass automatic 
        // application/x-www-form-urlencoded content type.
        $opts = array(
            CURLOPT_URL => $url,        
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_CUSTOMREQUEST => 'POST',
            CURLOPT_USERAGENT => 'mashery_api_call/1.0',
            CURLOPT_HTTPHEADER => array(
                'Content-Type: application/json',
                'Content-Length: ' . strlen($post_body) . "\r\n",
                $post_body
            )
        );
        curl_setopt_array($ch, $opts);
        $response = curl_exec($ch);
        $headers = curl_getinfo($ch);
        curl_close($ch);
        
        return $response;
    }
    
    /**
     * Perform the API Call
     */
    function call($method, $parameters) 
    {

        // We can use a constant for id because we are not making
        // asyncronous calls
        $id = 1;

        // Build a PHP representation of the json-rpc request
        $call = array(
            'method' => $method,
            'params' => $parameters,
            'id' => $id, 
            );

        // Convert the php values to a json string
        $request = json_encode($call);

        // Make the api call
        $response = $this->httpPost($this->getEndpointUrl(), $request);
        
        // Decode the result
        return json_decode($response);
    }

}

A JSON-RPC Request for calling the test method

This is the formatted json that will be built and sent to the API in the the previous php example.

{
      "method": "test.echo",
      "params": ["Hello!"],
      "id": 1
}

The JSON-RPC Response

This is the formatted json that the API will return

{
    "result": "Hello!",
    "error": null,
    "id": 1
}

Actual Output

This is the actual output of the PHP example program, which reflects the internal PHP representation fo the decoded json response.

stdClass Object
(
    [result] => hello
    [error] => 
    [id] => 1
)

Testing the API with Curl

You can also make a test API Call using curl.  This is possilble as long as you have a valid signature.

The following cli command will generate a valid signature if you have php installed on the command line.

php -r "echo md5('yourapikey' . 'yoursecret' . gmdate('U'));"

Then use that signature in the following curl command.

curl -d \
     "{\"method\":\"test.echo\", \"params\": [\"Hello\"], \"id\":1}" \
     "http://api.mashery.com/v2/json-rpc/[site_id]?apikey=your_key_here&sig=your_generated_sig"

More complex testing with curl can be done by placing the JSON request in a file and using the following command syntax.

curl -d @FILE_NAME "URL"

Authentication Errors

The following errors are indicative of permission, capacity, or authentication issues.