Developers

Introduction

The Sexbyfood API exposes Sexbyfood restaurant content through an easy-to-use web service interface that, when combined with the Sexbyfood Associates Program, is a simple way for website developers to make money.

You may use the Sexbyfood API as long as it is used primarily to drive more honored Internet reservations to restaurants listed on Sexbyfood. Access to the Sexbyfood API is free.

Highlights

Easily incorporate rich Sexbyfood restaurant content into your own site including:

1. Real-time table availability searching
2. Restaurant profiles, information, images, menu's and special offers
3. Customer reviews and more

Receive 12.5% in referral fees on honored Internet reservations placed on your website through the Sexbyfood API.

Get Started

Get Started

• API Protocol
• Authentication
• Reading Resources
• Creating Resources
• Updating Resources
• Deleting Resources
• Content Negotiation
• Content Encoding
• Error Handling
• AJAX And Cross-Domain Requests
• Earning Referral Fees
• API Terms

API Protocol

The Sexbyfood API at http://www.sexbyfood.com/api/ enables access to specific Sexbyfood resources, each of which can be referred to by a uniform resource identifier or URI. Sexbyfood resources can be manipulated over HTTP using the verbs GET, POST, PUT and DELETE. Resources can be exchanged as either JSON or XML representations. In other words, the Sexbyfood API is based on REST.

Top

Authentication

When you use the Sexbyfood API you have access to everything that your Sexbyfood account has access to. Please sign in to view your Sexbyfood API authentication credentials.

The Sexbyfood API authenticates using HTTP Basic Authentication. You must include an Authorization header in every request to the Sexbyfood API. This consists of your API ID, a UTC timestamp and a hex MD5 hash of the UTC timestamp and your Authentication Token:

$utc_timestamp = gmmktime(); //generated within an hour of each request

$credentials = $api_id . ':' . $utc_timestamp . md5($utc_timestamp . $authentication_token);

$authorization_header = 'Authorization: Basic ' . base64_encode($credentials);

Anyone who has your Sexbyfood API ID and Authentication Token can see and change everything you have access to. If your Authentication Token may have been compromised, please change your Sexbyfood password to regenerate your Authentication Token.

Top

Reading Resources

To read a resource, perform a GET on the resource URI.

The response to a successful resource read is the requested resource represented in your requested format and an HTTP status code header of '200 OK'.

Top

Creating Resources

To create a resource, perform a POST on the URI of the resource to be created and include the new resource in the body of your request.

The response to a successful resource creation is the created resource represented in your requested format and an HTTP status code header of '201 CREATED'.

Top

Updating Resources

To update a resource, perform a PUT on the URI of the resource you want to update and include the updated resource in the body of your request. To perform a PUT on a resource URI, perform a POST on the resource URI and set the method override header as 'X-HTTP-Method-Override: PUT'.

The response to a successful resource update is the updated resource represented in your requested format and an HTTP status code header of '200 OK'.

Top

Deleting Resources

To delete a resource, perform a DELETE on the URI of the resource you want to delete. To perform a DELETE on a resource URI, perform a POST on the resource URI and set the method override header as 'X-HTTP-Method-Override: DELETE'.

The response to a successful resource delete is an HTTP status code header of '200 OK'.

Top

Content Negotiation

The Sexbyfood API uses content negotation to exchange resources as either JSON or XML representations. To indicate which representation you wish to exchange, specify an 'Accept' HTTP header for GET requests and a 'Content-Type' HTTP header for POST and PUT requests. The relevant MIME media-type to include in your header is 'application/json' for JSON or 'application/xml' for XML.

Top

Content Encoding

The Sexbyfood API expects data to be UTF-8 encoded. Checks are made for valid UTF-8 sequences. If an invalid sequence is found, the data is presumed to be ISO-8859-1 and is converted accordingly to UTF-8.

Top

Error Handling

The response to a failed resource request is an HTTP status code header of either: 400 Bad Request, 401 Unauthorized, 404 Not Found, 405 Method Not Allowed, 415 Unsupported Media Type or 500 Internal Server Error.

A '400 Bad Request' response is accompanied with a custom 'X-Error-Message' header to indicate errors in the request. The 'X-Error-Message' header is designed to be end-user friendly. A '500 Internal Server Error' response indicates an error internal to Sexbyfood. Please contact us at info@sexbyfood.com should such an error persist or should you wish to receive error messages in Cantonese.

Top

AJAX And Cross-Domain Requests

The Sexbyfood API is designed to be AJAX friendly. We recommend that you use the excellent cross-browser Prototype Javascript library when making AJAX calls to the Sexbyfood API. Prototype provides helpers for AJAX requests, JSON and custom headers.

We further recommend that you use our Javascript serialize method when serializing your HTML forms to JSON as it has support for nested HTML form elements.

For security reasons, AJAX requests can only be made to URLs of the same protocol, host and port as the page containing the AJAX request. To access the Sexbyfood API through AJAX you need to install a proxy on your web server.

A proxy can be a single line in your Apache .htaccess file or a server-side script. Instead of making your AJAX request to the Sexbyfood API, make your AJAX request to your proxy. Your proxy passes the request onto the Sexbyfood API and then returns the response to your client application. Because the connection is made to your server, and the data comes back from your server, the browser has nothing to complain about.

Top

Earning Referral Fees

To earn referral fees for referring honored Internet reservations, find out more about the Sexbyfood Associates Program. You will receive a Sexbyfood Associate ID to identify you. Include your Sexbyfood Associate ID in each Sexbyfood API request where applicable to receive referral fees for honored Internet reservations referred by you.

Top

API Terms

Use of the Sexbyfood API is governed by the Sexbyfood API Terms. Before starting, make sure you have read and agree to the Sexbyfood API Terms.

Top

API Resources

• Listings
• Images
• Reviews
• Users
• World
• Categories
• Currencies
• Greetings

API Sandbox

HTTP Request

API ID:

Authentication Token:

Method:

GET POST PUT DELETE

Resource URI:

(What Is This?)

MIME Media-Type:

application/json application/xml

Representation:

 

API Code

• Javascript: Apache .Htaccess Proxy
• Javascript: Authorization Header
• Javascript: Request Wrapper
• Javascript: Serialize Method
• PHP: Request Wrapper

Javascript: Apache .Htaccess Proxy

To access the Sexbyfood API using Javascript, you need to install a proxy to enable cross-domain AJAX requests. This is clean and simple if your website runs on Apache. Just include the following lines in your Apache .htaccess file:

RewriteEngine on
RewriteRule ^/sexbyfood/api/(.*)$ http://www.sexbyfood.com/api/$1 [P]

Top

Javascript: Authorization Header

Your authorization header expires an hour after it is generated. Include the following script tag at the top of each HTML page that initiates a request. This enables you to generate the authorization header dynamically and make it available as a global Javascript variable to your external Javascript files:

<script type="text/javascript">

var AUTHORIZATION = 'Basic: <?php $gmt_timestamp = gmmktime(); echo base64_encode($api_id . ':' . $gmt_timestamp . md5($gmt_timestamp . $authentication_token)); ?>';

</script>

Top

Javascript: Request Wrapper

We recommend that you use the following request wrapper (requires Prototype Version 6) to make your AJAX requests. Simply paste the wrapper wherever you need to make a request, modify as required by the request method, and use the onSuccess and onFailure functions to act on the response accordingly:

new Ajax.Request(

   'http://www.your-domain-name.com/sexbyfood/api/listings', {

      method : 'GET',   //'GET', 'POST', 'PUT' or 'DELETE'
      
      requestHeaders : {
      
         'Authorization' : AUTHORIZATION,   //Note comma between key : value pairs
         'Accept' : 'application/json'      //Use only for GET requests
         
         //'X-HTTP-Method-Override' : 'PUT'      //Use only for PUT requests
         //'X-HTTP-Method-Override' : 'DELETE'   //Use only for DELETE requests
      
      },
      //contentType : 'application/json'   //Use only for POST and PUT requests
      //postBody : Object.toJSON($('id-of-form-to-serialize').serialize(true)),
      //Use only for POST and PUT requests, insert 'id-of-form-to-serialize'
      
      onSuccess : function(ajax) {
         
         var listings = ajax.responseJSON.listings;
         
         alert('The first listing has id: ' + listings[0].listing.id);
      
      },
      
      onFailure : function(ajax) {
      
         alert(ajax.getHeader('X-Error-Message'));
      
      }
   
   }

);

Top

Javascript: Serialize Method

We recommend that you use the following Javascript serialize method when serializing your HTML forms to JSON as it has support for nested HTML form elements. Nested form elements are necessary to produce resource representations that adhere to the relevant schema. This method is designed to replace Prototype's native serialize method (line 3374 in Prototype Version 6) which does not support nested form elements.

The method serializes form data to an object hash where keys are form element names and values are data. If a form name is provided, this is used as the object hash root. Only elements with a name attribute are serialized. Disabled form elements and submit inputs are not serialized (as per the W3C HTML recommendation). File inputs are skipped as they cannot be serialized by Javascript. See the Javascript request wrapper above for usage.

serialize: function(form, options) {

   var serialization = {}, root = ($(form).attributes['name'] ? $(form).attributes['name'].value : '');
   
   if (root) eval('serialization["' + root + '"] = {};');

   $(form).getElements().each(function(element) {

      if (!element.disabled && element.name) {
         
         if ($F(element) != null && element.type != 'submit') {
         
            var keys = $w(element.name.gsub(/\[\]/, '[-]').gsub(/\[/, ' ').gsub(/\]/, ''));
            
            var variable = 'serialization';

            if (root) variable = 'serialization["' + root + '"]';
            
            keys.each(function(key, index) {
               
               if (key == '-') key = eval(variable + '.length;');
               
               variable += '["' + key + '"]';
            
               if (index < keys.length - 1) {
                  
                  if (!eval(variable)) {
                  
                     if (keys[index + 1] * 1 >= 0 || keys[index + 1] == '-') {
                     
                        eval(variable + '= [];');
                                                
                     } else {
                     
                        eval(variable + '= {};');
                        
                     }
                  
                  }
               
               } else {
               
                  if (eval(variable)) {

                     eval(variable + ' = $A(' + variable + ');');
                     eval(variable + '.push($F(element));');
                     
                  } else {
                  
                     eval(variable + ' = $F(element)');
                     
                  }
                  
               }
            
            });

         }
      
      }

   });

   return serialization;
   
}

Top

PHP: Request Wrapper

If you use PHP, the following PHP wrapper simplifies access to the Sexbyfood API. Pass in your method, resource and representation (as a PHP array). The wrapper returns the response HTTP status code. Where applicable the wrapper also returns an error message, and a representation (as a PHP array).

function sexbyfood($method, $resource, $representation = '') {
   
   //authorization credentials
   $api_id = '';
   $authentication_token = '';
   
   require_once('xml.php');
   $xml = new xml();
   
   if ($representation) $representation = $xml->encode($representation);
   
   $gmt_timestamp = gmmktime();
   $credentials = $api_id;
   $credentials .= ':' . $gmt_timestamp;
   $credentials .= md5($gmt_timestamp . $authentication_token);
   $headers[] = 'Authorization: Basic: ' . base64_encode($credentials);
   
   switch(strtoupper($method)) {
   
      case 'GET':
         $method = 'GET';
         $headers[] = 'Accept: application/xml';
      break;
      
      case 'POST':
         $method = 'POST';
         $headers[] = 'Content-Type: application/xml';
      break;
      
      case 'PUT':
         $method = 'POST';
         $headers[] = 'Content-Type: application/xml';
         $headers[] = 'X-HTTP-Method-Override: PUT';
      break;
      
      case 'DELETE':
         $method = 'POST';
         $headers[] = 'X-HTTP-Method-Override: DELETE';
      break;
   
   }
   
   $curl = curl_init();
   curl_setopt($curl, CURLOPT_URL, 'http://www.sexbyfood.com/api/' . $resource);
   
   if ($method == 'POST') {
   
      curl_setopt($curl, CURLOPT_POST, TRUE);
      if ($representation) curl_setopt($curl, CURLOPT_POSTFIELDS, $representation);
   
   }
   
   curl_setopt($curl, CURLOPT_HEADER, TRUE);
   curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
   curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
   
   $response = explode("\n\r\n", curl_exec($curl), 2);
   
   $status = curl_getinfo($curl, CURLINFO_HTTP_CODE);
   
   $error = NULL;
   preg_match("/X-Error-Message:\s([^\n]*)/s", $response[0], $matches);
   if (isset($matches[1])) $error = $matches[1];
   
   $representation = NULL;
   if (isset($response[1])) $representation = $xml->decode($response[1]);
   
   curl_close($curl);
   
   return array(
   
      'status' => $status,
      'error' => $error,
      'representation' => $representation
   
   );

}

$result = sexbyfood('GET', 'listings/62');

print_r($result);

Top

API Terms

Associates, developers, restaurants and users may access Sexbyfood data via the Sexbyfood API (Application Program Interface). Any use of the API, including use of the API through a third-party product that accesses Sexbyfood, is bound by the Sexbyfood terms of service plus the following specific terms:

1. You expressly understand and agree that Sexbyfood shall not be liable for any direct, indirect, incidental, special, consequential or exemplary damages, including but not limited to, damages for loss of profits, goodwill, use, data or other intangible losses (even if Sexbyfood has been advised of the possibility of such damages), resulting from your use of the API or third-party products that access data via the API.


2. Abuse or excessively frequent requests to Sexbyfood via the API may result in the temporary or permanent suspension of your account's access to the API. Sexbyfood, in its sole discretion, will determine abuse or excessive usage of the API. Sexbyfood will make a reasonable attempt via email to warn the account owner prior to suspension.


3. Sexbyfood reserves the right at any time to modify or discontinue, temporarily or permanently, your access to the API (or any part thereof) with or without notice.