General API Requirements

Applications that use the SinglePlatform APIs must abide by all existing Terms of Service. Most importantly, you must correctly identify your requests.

...

Most requests should contain a valid DOCS:#API API Key.

Some requests require authentication using a Client ID and a Signing Key. See DOCS:#API API Authentication.

API Key

The API Key is used in many requests made to the SinglePlatform APIs. Though the API Key is not required for requests that accept it, the API Key should be provided. This allows us to contact you in the event of issues with your application.

...

In a URL, your key would be used like this:

http://menus.singleplatform.co/restaurantslocations/haru-7/menusmenu?apiKey=YOUR_API_KEY_HERE

In the JavaScript API, your key would be used like this:

<script type="text/javascript" src="http://menus.singleplatform.co/jsload?load=menus.2&apiKey=YOUR_API_KEY_HERE"></script>
<script>
    var menuApi = new MenusApi("YOUR_API_KEY_HERE");
    menuApi.loadMenusForLocation("haru-7", "menusContainer");
</script>

...

These are the steps you should use to sign a valid URL:

1. Construct your URL. Make sure to include the clientparameter. Note, any non-standard characters need to be URL-encoded.

   Code Block
   http://api.singleplatform.co/restaurantslocations/haru-7?client=YOUR_CLIENT_ID

   Note
   All SinglePlatform services require UTF-8  8   character encoding, which implicitly includes ASCII. Make sure your applications construct URLs using UTF-8  8   and properly URL-encoded characters, particularly if your application works with other character sets.

2. Strip off the domain portion of the request, leaving only the path and the query:

   Code Block
   /restaurantslocations/haru-7?client=YOUR_CLIENT_ID

3. Retrieve your private key, which is encoded in a modified Base64 for URLs, and sign the URL above using the HMAC-SHA1 algorithm. You may need to decode the Signing Key into its original binary format. In many cryptographic libraries, the resulting signature will be in binary format.
4. Encode the resulting binary signature using the modified Base64 for URLs to convert this signature into something that can be passed within a URL.

5. Attach this signature to the URL with a sigparameter:

   Code Block
   http://api.singleplatform.co/restaurantslocations/haru-7?client=YOUR_CLIENT_ID&sig=BASE64_SIGNATURE

...

You may think that a "valid" URL is self-evident, but that's not quite the case. A URL entered within an address bar in a browser, for example, may contain special characters (e.g. "éîñå"); the browser needs to internally translate those characters into a different encoding before transmission. By the same token, any code that generates or accepts UTF-8  8   input might treat URLs with UTF-8  8   characters as "valid", but would also need to translate those characters before sending them out to a web server. This process is called URL-encoding.

...

All characters to be URL-encoded are encoded using a '%' character and a two-character hex value corresponding to their UTF-8  8   character. For example, éîñå in UTF-8  8   would be URL-encoded as %8E%94%96%8C. The string ? is a bulldog would be URL-encoded as %3F+is+a+bulldog.

...

Additionally, URLs are limited to 2048 characters for all web services. For most services, this character limit will seldom be approached. However, certain services have several parameters that may result in long URLs.

Sample Libraries

Sample libraries are available for download if you need assistance generating valid URLs:

• Python
• Ruby
• PHP
• Java