Sample Applications

From API Documentation

(Difference between revisions)
Jump to: navigation, search
(Created page with 'Below are sample applications built using the API, coded using PHP. These samples demonstrate a variety of common use cases. While we do not cover every possible use of the API h…')
(→form.html)
 
(9 intermediate revisions not shown)
Line 1: Line 1:
-
Below are sample applications built using the API, coded using PHP. These samples demonstrate a variety of common use cases. While we do not cover every possible use of the API here, these samples are meant to be indicative of all API calls.
+
Below are sample applications built using the API, coded in PHP. These samples demonstrate a variety of common use cases. While we do not cover every possible use of the API here, these samples are meant to be indicative of all API calls.
-
All examples use the cURL library for handling the HTTP request. There are other methods available in PHP (and other languages, of course), and any method that allows you to send and receive the properly formatted requests and responses is perfectly acceptable.
+
All samples use the cURL library for handling the HTTP request. There are other methods available in PHP (and other languages, of course), and any method that allows you to send and receive the properly formatted requests and responses is perfectly acceptable.
== Sample 1: mailing list signup form ==
== Sample 1: mailing list signup form ==
-
This application allows a site visitor to add himself or herself to an agent's consists  
+
This application allows a site visitor to add himself or herself to a an agent's contact list, while also adding the new contact to a predefined distribution list. The application consists of two files: an HTML file containing a simple signup form, and a PHP file which processes form submissions and makes the necessary API calls.
 +
 
 +
The files are included below, or you can [http://api.rezora.com/documentation/samples/rezora_api_add_contact_form.zip download them here].
 +
 
 +
=== form.html ===
 +
The form contains two fields: name, and email address.  However, this could be expanded to include any of the fields supported by the contacts collection resource.
 +
<source lang="html4strict">
 +
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 +
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 +
  <head>
 +
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 +
    <title>Rezora API Sample: Add a Contact</title>
 +
  </head>
 +
  <body>
 +
    <h1>Add a Contact</h1>
 +
    <form action="form_processor.php" method="post" name="addcontactform" id="addcontactform">
 +
      <div>
 +
        <label for="name">Name:</label>
 +
        <input type="text" name="name" id="name" value="" />
 +
      </div>
 +
      <div>
 +
        <label for="email">Email address:</label>
 +
        <input type="text" name="email" id="email" value="" />
 +
      </div>
 +
      <div>
 +
        <input type="submit" value="Submit" />
 +
      </div>
 +
    </form>
 +
  </body>
 +
</html>
 +
</source>
 +
 
 +
=== form_processor.php ===
 +
This script should be considered a starting point, and requires some customization, notably in the areas of user input validation and user response messages.
<source lang="php">
<source lang="php">
<?php
<?php
-
// Set some universal configuration variables. These will be
+
/*
-
// the same for all your API requests for a particular account.
+
* This script uses the Rezora Agent API to add a new contact entry to an agent's account,
-
$strUsername = 'YOUR_API_USERNAME';
+
* and to add that contact to a specified Distribution List so that newly added contacts
-
$strPassword = 'YOUR_API_PASSWORD';
+
* may be easily identified by the agent from within the Rezora system.
-
$strBaseURI = 'http://api.rezora.com/v1/';
+
* See http://api.rezora.com/ for the full API documentation.
 +
*/
 +
 
 +
// Set some configuration constants.
 +
// Your Agent API Key username and password are available on your Rezora My Account page.
 +
define('API_USERNAME', 'YOUR_API_USERNAME');
 +
define('API_PASSWORD', 'YOUR_API_PASSWORD');
 +
define('API_BASEURI', 'http://api.rezora.com/v1/');
 +
define('API_FORMAT', 'application/json');
 +
 
 +
// Set the ID of the distribution list to which new contacts will be added.
 +
// You should create a distribution list (called something like "Website Signup") exclusively for this purpose.
 +
// You can get the ID of a lsit by using the Lists API Resource, or by noting the ID in the HTML code on the agent's Contacts page within the Rezora system.
 +
// Leave the value as zero to skip this step (not recommended).
 +
$intListID = 0;
 +
 
 +
// Validate the user-submitted form data before proceding
 +
if (validateUserData()) {
 +
  // First, we'll be posting data to the contacts collection resource to create a new contact.
 +
  // Set some configuration variables specific to the task at hand.
 +
  $strResource = 'contacts';
 +
  $strData = '{
 +
    "data":{
 +
      "contact_name":"' . $_POST['name'] . '",
 +
      "contact_email":"' . $_POST['email'] . '"
 +
    }
 +
  }';
 +
 
 +
  // Post the API request
 +
  $arrResponse = doAPIPost($strResource, $strData);
 +
 
 +
  // Make sure we successfully added the contact before continuing
 +
  if ($intListID > 0 && $arrResponse['status'] == 200) {
 +
    // Next, we'll be posting data to the lists/ID/contacts collection resource to associate the new contact with the specified distribution list.
 +
    // Set some configuration variables specific to the task at hand.
 +
    $strResource = 'lists/' . $intListID . '/contacts';
 +
    $strData = '{
 +
      "data":{
 +
        "contact_id":"' . $arrResponse['body'][0]->contact_id . '"
 +
      }
 +
    }';
 +
 
 +
    // Post the API request
 +
    $arrResponse = doAPIPost($strResource, $strData);
 +
  }
 +
 
 +
  // Get a status message to diplay to the user.
 +
  $strMessage = getStatusMessage($arrResponse['status']);
 +
} else {
 +
  // Send a message to the user explaining wehat they have done wrong.
 +
  // Your validateUserData() function should probably provide detailed error messages.
 +
  $strMessage = 'You must provide valid information. Please try again.';
 +
}
 +
 
 +
// Function for validating the user-submitted form data
 +
function validateUserData() {
 +
  // You'll probably want to put some code here to validate whatever input you're receiving from the user.
 +
  return true;
 +
}
 +
 
 +
// Make an API POST request
 +
function doAPIPost($strResourcePath, $strData) {
 +
  // Open a cURL resource
 +
  $ch = curl_init();
 +
 
 +
  // Set the necessary parameters
 +
  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
 +
  curl_setopt($ch, CURLOPT_USERPWD, API_USERNAME . ':' . API_PASSWORD);
 +
  curl_setopt($ch, CURLOPT_URL, API_BASEURI . $strResourcePath);
 +
  curl_setopt($ch, CURLOPT_HTTPHEADER, array ('Accept: ' . API_FORMAT, 'Content-type: ' . API_FORMAT));
 +
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 +
 
 +
  // Make this a POST request
 +
  curl_setopt($ch, CURLOPT_POST, true);
 +
  curl_setopt($ch, CURLOPT_POSTFIELDS, $strData);
 +
 
 +
  // Make the request and capture the response and status code.
 +
  $arrResponse['body'] = json_decode(curl_exec($ch));
 +
  $arrResponse['status'] = curl_getinfo($ch, CURLINFO_HTTP_CODE);
 +
 
 +
  // Close the cURL resource
 +
  curl_close($ch);
-
// Set some configuration variables specific to the task at hand.
+
  return $arrResponse;
-
// In this example, we'll be reading data from the agents collection
+
}
-
// resource. We'll retrieve the data in CSV format.
+
-
$strResourcePath = 'agents';
+
-
$strRequestFormat = 'text/plain';
+
-
$strResponseFormat = 'text/csv';
+
-
// Open a cURL resource
+
// Return a status message to display to the user.
-
$ch = curl_init();
+
function getStatusMessage($strStatus) {
 +
  // An array of all status codes.
 +
  // These descriptions are rather technical. You may want to make them more user-friendly for production.
 +
  $arrStatuses = array(
 +
    '200' => 'The request was successfully processed.',
 +
    '204' => 'The request was formatted correctly, but no data was found for the specified resource.',
 +
    '400' => 'Your data has failed a validation test.',
 +
    '401' => 'Either your username or password are incorrect, or you are attempting to access a resource that is not available for your user type.',
 +
    '404' => 'The resource you have requested does not exist.',
 +
    '405' => 'The method you are attempting to use (GET, POST, PUT, or DELETE) is not allowed for the resource you have requested.',
 +
    '500' => 'The API experienced an internal error while attempting to process your request.',
 +
    '501' => 'The method you are attempting to use (GET, POST, PUT, or DELETE) has not yet been implemented, but may be in a future release.'
 +
  );
 +
  // Look up the message that corresponds to the status code
 +
  if (array_key_exists($strStatus, $arrStatuses)) {
 +
    $strMessage = $arrStatuses[$strStatus];
 +
  } else {
 +
    // Use a default message if no match was found
 +
    $strMessage = 'An unknown error occurred while attempting to add your information. Please try again.';
 +
  }
 +
  return $strMessage;
 +
}
 +
?>
 +
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 +
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
 +
  <head>
 +
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 +
    <title>Rezora API Sample: Add a Contact</title>
 +
  </head>
 +
  <body>
 +
    <?php echo $strMessage ?>
 +
  </body>
 +
</html>
 +
</source>

Latest revision as of 14:07, 5 October 2012

Below are sample applications built using the API, coded in PHP. These samples demonstrate a variety of common use cases. While we do not cover every possible use of the API here, these samples are meant to be indicative of all API calls.

All samples use the cURL library for handling the HTTP request. There are other methods available in PHP (and other languages, of course), and any method that allows you to send and receive the properly formatted requests and responses is perfectly acceptable.

Sample 1: mailing list signup form

This application allows a site visitor to add himself or herself to a an agent's contact list, while also adding the new contact to a predefined distribution list. The application consists of two files: an HTML file containing a simple signup form, and a PHP file which processes form submissions and makes the necessary API calls.

The files are included below, or you can download them here.

form.html

The form contains two fields: name, and email address. However, this could be expanded to include any of the fields supported by the contacts collection resource.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Rezora API Sample: Add a Contact</title>
  </head>
  <body>
    <h1>Add a Contact</h1>
    <form action="form_processor.php" method="post" name="addcontactform" id="addcontactform">
      <div>
        <label for="name">Name:</label>
        <input type="text" name="name" id="name" value="" />
      </div>
      <div>
        <label for="email">Email address:</label>
        <input type="text" name="email" id="email" value="" />
      </div>
      <div>
        <input type="submit" value="Submit" />
      </div>
    </form>
  </body>
</html>

form_processor.php

This script should be considered a starting point, and requires some customization, notably in the areas of user input validation and user response messages.

<?php
/*
* This script uses the Rezora Agent API to add a new contact entry to an agent's account, 
* and to add that contact to a specified Distribution List so that newly added contacts
* may be easily identified by the agent from within the Rezora system.
* See http://api.rezora.com/ for the full API documentation.
*/
 
// Set some configuration constants.
// Your Agent API Key username and password are available on your Rezora My Account page.
define('API_USERNAME', 'YOUR_API_USERNAME');
define('API_PASSWORD', 'YOUR_API_PASSWORD');
define('API_BASEURI', 'http://api.rezora.com/v1/');
define('API_FORMAT', 'application/json');
 
// Set the ID of the distribution list to which new contacts will be added.
// You should create a distribution list (called something like "Website Signup") exclusively for this purpose.
// You can get the ID of a lsit by using the Lists API Resource, or by noting the ID in the HTML code on the agent's Contacts page within the Rezora system.
// Leave the value as zero to skip this step (not recommended).
$intListID = 0;
 
// Validate the user-submitted form data before proceding
if (validateUserData()) {
  // First, we'll be posting data to the contacts collection resource to create a new contact.
  // Set some configuration variables specific to the task at hand.
  $strResource = 'contacts';
  $strData = '{
    "data":{
      "contact_name":"' . $_POST['name'] . '",
      "contact_email":"' . $_POST['email'] . '"
    }
  }';
 
  // Post the API request
  $arrResponse = doAPIPost($strResource, $strData);
 
  // Make sure we successfully added the contact before continuing
  if ($intListID > 0 && $arrResponse['status'] == 200) {
    // Next, we'll be posting data to the lists/ID/contacts collection resource to associate the new contact with the specified distribution list.
    // Set some configuration variables specific to the task at hand.
    $strResource = 'lists/' . $intListID . '/contacts';
    $strData = '{
      "data":{
        "contact_id":"' . $arrResponse['body'][0]->contact_id . '"
      }
    }';
 
    // Post the API request
    $arrResponse = doAPIPost($strResource, $strData);
  }
 
  // Get a status message to diplay to the user.
  $strMessage = getStatusMessage($arrResponse['status']);
} else {
  // Send a message to the user explaining wehat they have done wrong.
  // Your validateUserData() function should probably provide detailed error messages.
  $strMessage = 'You must provide valid information. Please try again.';
}
 
// Function for validating the user-submitted form data
function validateUserData() {
  // You'll probably want to put some code here to validate whatever input you're receiving from the user.
  return true;
}
 
// Make an API POST request
function doAPIPost($strResourcePath, $strData) {
  // Open a cURL resource
  $ch = curl_init();
 
  // Set the necessary parameters
  curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST);
  curl_setopt($ch, CURLOPT_USERPWD, API_USERNAME . ':' . API_PASSWORD);
  curl_setopt($ch, CURLOPT_URL, API_BASEURI . $strResourcePath);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array ('Accept: ' . API_FORMAT, 'Content-type: ' . API_FORMAT));
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 
  // Make this a POST request
  curl_setopt($ch, CURLOPT_POST, true);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $strData);
 
  // Make the request and capture the response and status code.
  $arrResponse['body'] = json_decode(curl_exec($ch));
  $arrResponse['status'] = curl_getinfo($ch, CURLINFO_HTTP_CODE);
 
  // Close the cURL resource
  curl_close($ch);
 
  return $arrResponse;
}
 
// Return a status message to display to the user.
function getStatusMessage($strStatus) {
  // An array of all status codes.
  // These descriptions are rather technical. You may want to make them more user-friendly for production.
  $arrStatuses = array(
    '200' => 'The request was successfully processed.',
    '204' => 'The request was formatted correctly, but no data was found for the specified resource.',
    '400' => 'Your data has failed a validation test.',
    '401' => 'Either your username or password are incorrect, or you are attempting to access a resource that is not available for your user type.',
    '404' => 'The resource you have requested does not exist.',
    '405' => 'The method you are attempting to use (GET, POST, PUT, or DELETE) is not allowed for the resource you have requested.',
    '500' => 'The API experienced an internal error while attempting to process your request.',
    '501' => 'The method you are attempting to use (GET, POST, PUT, or DELETE) has not yet been implemented, but may be in a future release.'
  );
  // Look up the message that corresponds to the status code
  if (array_key_exists($strStatus, $arrStatuses)) {
    $strMessage = $arrStatuses[$strStatus];
  } else {
    // Use a default message if no match was found
    $strMessage = 'An unknown error occurred while attempting to add your information. Please try again.';
  }
  return $strMessage;
}
?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Rezora API Sample: Add a Contact</title>
  </head>
  <body>
    <?php echo $strMessage ?>
  </body>
</html>
Personal tools