Difference between revisions of "Rest API"

Revision as of 10:15, 2 September 2009

Introduction

The Email API provides most of the functions of Rackspace's Email and Apps Control Panel through a web-based API (Application Programming Interface). Whether it is adding a new customer account, adding mailboxes, or any other of the supported features the API allows your application to administer the changes regardless of your application's language or environment. The API is a RESTful web service based on the Hypertext Transfer Protocol (HTTP). Actions and data requests are performed by using HTTP-based commands. For more information on RESTful web services refer to the following sites:

http://en.wikipedia.org/wiki/Representational_State_Transfer

http://java.sun.com/developer/technicalArticles/WebServices/restful/

Right now the API is in its beta release and is restricted to resellers only.

Operations

The following pages detail the operations that the API supports. The operations are grouped into sections based on the entity/object types that each operation interacts with.

The examples shown in the subpages are written in Ruby and extensively use the helper functions shown in the Ruby Examples below.

Accessing the API

Your application will need to make HTTP calls to remote servers. Most programming languages have this function provided in its class library. In addition to the common GET and POST HTTP methods, the library used will also need to support PUT and DELETE. All API calls should be directed to a URL in the format

http://api.emailsrvr.com/(version)/(resource)

Example:

http://api.emailsrvr.com/v0/customers/12345678/domains/customerbusiness.com

Versions

The API version number is a component of the URL that is used to access the API. For example, to access the root of the API, the URL is http://api.emailsrvr.com/v0/. Bug fixes and minor non-breaking changes will be made without changing the version number. When major features or breaking changes are introduced, the version number will be incremented. It is not yet determined how many versions are going to be supported at any one time.

Note: Pre-release versions of the API will be located at http://api.emailsrvr.com/v0/.

Authentication

To gain access to the API, you must have keys generated from the Control Panel Web interface. These keys will be used to sign your request. The two keys are:

Requests to the API must then include HTTP headers with the following information:

An unsuccessful authentication will result in a 403 HTTP code.

X-Api-Signature Header

Format is as follows:

<User Key>:<Timestamp>:<Signature>

Example: eGbq9/2hcZsRlr1JV1Pi:20010317143725:HKUn0aajpSDx7qqGK3vqzn3FglI=

User Key:
This is the public key issued by the Control Panel interface.

Timestamp:
The format is YYYYMMDDHHmmssff. All values besides year are zero-padded to two spaces. For example, March 17th 2001 at 2:37.25pm would be 20010317143725.

Signature:

A SHA1 (Secure Hash Algorithm) hash must be applied to a string with the following information:

<User Key><User Agent><Timestamp><Secret Key>

Using the above example data, the string before hashing is:
eGbq9/2hcZsRlr1JV1PiRackspace Management Interface20010317143725QHOvchm/40czXhJ1OxfxK7jDHr3t

Resulting base-64 SHA1 Hash:
HKUn0aajpSDx7qqGK3vqzn3FglI=

Be sure to encode the binary hash, not the hex hash, into base-64. The resulting string should be 28 characters long.

Throttling

The server limits the number of requests allowed per user in a certain period of time. The current limit is 2500 requests over 5 minutes. The number of requests made are logged per minute. Calls that were made correctly with a user's API key, but not completed for any reason, including those exceeding the throttle limit, are included in this count.

If a user is over the throttling limit then a 403 HTTP code will be returned with an "Exceeded request limits" message.

Formats

The Email API supports two different response formats, XML and JSON. The response format is determined by HTTP 'Accept' header.

For XML, populate the header with 'text/xml' (ex: Headers!["Accept"] = "text/xml"). The XML document returned will conform to a published XSD (XML Schema Document).

For JSON, populate the header with 'application/json' (ex: Headers!["Accept"] = "application/json").

Paging

The results of Index actions are split into pages to lessen potentially high resource usage. The index URLs have a query string with parameters in the format "?size=xx&offset=xx." If a query parameter is omitted, the default value is used.

Filter/Search

The results of Index actions can be filtered/searched. The index URLs can take either one of the query strings: "?startswith=xx" or "?contains=xx," where "xx" is the key word. If the request specifies more than one of these two query strings, a 400 HTTP error will be returned. Different fields will be searched depending on the resource type, see below.

Note that "0-9" is a reserved key word for query string "startswith." It represents any result starting with numbers.

Reference Number

For the customer object only, the query string "referenceNumber=xx" searches for a customer with an exact reference number. The result if found is the detail page of the customer.

Examples

Ruby

This examples is written in Ruby. To make the examples shorter, helper methods have been written. These methods are part of a NetMethods module. The contents of the NetMethods module is listed below.

module NetMethods 
  def get(url_string, format)
    url = URI.parse('http://' + server_host + server_port + version + url_string)
    @response = Net::HTTP::start(url.host, url.port)  do |http|
      sign_request
      assign_format(format)
      @request = Net::HTTP::Get.new(url.path, @headers)
      
      http.request(@request)
    end
  end
  
  def post(url_string, format, fields_hash)
    url = URI.parse('http://' + server_host + server_port + version + url_string)

    sign_request
    assign_format(format)
    @request = Net::HTTP::Post.new(url.path, @headers)
	
    @request.set_form_data(fields_hash)
    @response = Net::HTTP::start(url.host, url.port) do |http| 
      http.request(@request)
    end
  end

  def assign_format (format)
    @headers['Accept'] = format
  end
    
  def sign_request
    userAgent = 'Ruby Test Client'
    timestamp = DateTime.now.new_offset.strftime('%Y%m%d%H%M%S00')
    apiKey = 'XXXXXXXXXXXXXXXXXXXX'
    secretKey = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
    
    data_to_sign = apiKey + userAgent + timestamp + secretKey
    
    signature = Base64.encode64(Digest::SHA1.digest(data_to_sign))
    
    @headers = Hash.new
    @headers['User-Agent'] = userAgent
    @headers['X-Api-Signature'] = apiKey + ":" + timestamp + ":" + signature 
  end
  
  def server_host
    'api.emailsrvr.com'
  end
  
  def server_port
    '80'
  end

  def version
    '/v0'
  end
end 

C#

This examples is written in C#.

using System;
using System.Collections.Specialized;
using System.Security.Cryptography;
using System.Text;
using System.Net;

public class WebMethods
{
  private WebClientBase client;
  private string baseUrl;
  private string apiKey;
  private string secretKey;

  public WebMethods(WebClientBase client, string baseUrl, string apiKey, string secretKey)
  {
    this.client = client;
    this.baseUrl = baseUrl;
    this.apiKey = apiKey;
    this.secretKey = secretKey;
  }

  public virtual string Get(string url)
  {
    return MakeRemoteCall((client) =>
      {
        return client.DownloadString(baseUrl + url);
      },
      format);
  }

  public virtual string Post(string url, NameValueCollection data)
  {
    return MakeRemoteCall((client) =>
      {
        var bytes = client.UploadValues(baseUrl + url, data);
        return Encoding.UTF8.GetString(bytes);
      },
      format);
  }

  private void SignMessage()
  {
    var userAgent = "C# Client Library";
    client.Headers["User-Agent"] = userAgent;

    var dateTime = DateTime.UtcNow.ToString("yyyyMMddHHmmssff");

    var dataToSign = apiKey + userAgent + dateTime + secretKey;
    var hash = SHA1.Create();
    var signedBytes = hash.ComputeHash(Encoding.UTF8.GetBytes(dataToSign));
    var signature = Convert.ToBase64String(signedBytes);

    client.Headers["X-Api-Signature"] = apiKey + ":" + dateTime + ":" + signature;
  }

  private void AssignFormat(string format)
  {
    client.Headers["Accept"] = format;
  }

  private string MakeRemoteCall(Func<WebClientBase, string> remoteCall, string format)
  {
    try
    {
      SignMessage();
      AssignFormat(format);
      return remoteCall.Invoke(client);
    }
    catch (WebException e)
    {
      throw new ApiException(e);
    }
  }
}

PHP

<?php
class WebMethods
{
    public function get($url, $format)
    {
        $headers = array();
        $this->signRequest($headers);
        $this->assignFormat($headers, $format);

        $session = curl_init($url);
        curl_setopt($session, CURLOPT_HEADER, true);
        curl_setopt($session, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($session, CURLOPT_RETURNTRANSFER, true);

        $response = curl_exec($session);
        curl_close($session);
    }

    public function post($url, $fields, $format)
    {
        $headers = array();
        $this->signRequest($headers);
        $this->assignFormat($headers, $format);

        $session = curl_init($url);
        curl_setopt($session, CURLOPT_HEADER, true);
        curl_setopt($session, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($session, CURLOPT_POST, true);
        curl_setopt($session, CURLOPT_POSTFIELDS, $fields);
        curl_setopt($session, CURLOPT_RETURNTRANSFER, true);

        $response = curl_exec($session);
        curl_close($session);
    }


    public function signRequest(&$headers)
    {
        $user_agent = 'Api Test';
        $time_stamp = 'YYYYMMDDHHmmssff';
        $api_key = 'XXXXXXXXXXXXXXXXXXXX';
        $secret_key = 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';

        $data_to_sign = $api_key . $user_agent . $time_stamp . $secret_key;
        $signature = base64_encode(sha1($data_to_sign, true));

        $headers[] = "User-Agent: $user_agent";
        $headers[] = "X-Api-Signature: $api_key:$time_stamp:$signature";
    }

    public function assignFormat(&$headers, $format)
    {
        $headers[] = "Accept: $format";
    }
}
?>