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.

Applications must always include a valid and accurate HTTP referrer header in their requests.

Most requests should contain a valid API Key.

Some requests require authentication using a Client ID and a Signing Key. See 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.

An API Key is provided upon request.

Example Usage of the API Key

Replace YOUR_API_KEY_HERE with the SinglePlatform API Key provided to you.

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

http://menus.singleplatform.co/locations/haru-7/menu?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>

API Authentication

Requests to some portions of the API require using a cryptographic Signing Key we provide to you for that purpose. The signing process combines a URL and the Signing Key together using an encryption algorithm, creating a unique signature. This signature allows our services to verify that any sites generating requests using your API Key are authorized to do so.

URL signing serves both to authenticate you to our web services as well as track your usage.

The URL Signing Process

Signing a URL involves generating a signature using a secret Signing Key shared between you and SinglePlatform. This signature is then attached to any HTTP (or HTTPS) requests. You generate this signature for a URL using the signing key, which creates a hash that is unique to that URL and the signing key. If the URL differs in any way from that used to generate the signature, the service will reject the request as invalid.

Attempting to access a web service with an invalid signature will result in an HTTP 403 (Forbidden) error.

Acquiring a Signing Key

Your cryptographic URL-signing key will be issued with your Client ID and is a "secret shared key" between you and SinglePlatform. Client IDs are issued to all SinglePlatform API customers. This Signing Key is yours alone and unique to your Client ID. For that reason, please keep your signing key secure. Though used to generate the signature, this key should not be passed within any requests, stored on any websites, or posted to any public forum. Anyone obtaining this Signing Key "in the clear" could spoof requests using your identity.

Note: The Signing Key and Client ID are not the same as the API Key.

Generating Valid Signatures

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.

   http://api.singleplatform.co/locations/haru-7?client=YOUR_CLIENT_ID
   

   All SinglePlatform services require UTF-8   character encoding, which implicitly includes ASCII. Make sure your applications construct URLs using UTF-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:

   /locations/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:

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

Building Valid URLs

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   input might treat URLs with UTF-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.

We need to translate special characters because all URLs need to conform to the syntax specified by the W3 Uniform Resource Identifier specification. In effect, this means that URLs must contain only a special subset of ASCII characters: the familiar alphanumeric symbols, and some reserved characters for use as control characters within URLs. The table below summarizes these characters:

When building a valid URL, you must ensure that it contains only those characters shown above. Two issues generally arise when conforming a URL to use this set of characters, one of omission and one of substitution:

• Characters that you wish to handle exist outside of the above set. For example, characters in foreign languages such as éîñå need to be encoded using the above characters. By popular convention, spaces (which are not allowed within URLs) are often represented using the plus '+' character as well.
• Characters exist within the above set as reserved characters, but need to be used literally. For example, ? is used within URLs to indicate the beginning of the query string; if you wish to use the string "? is a bulldog," you'd need to encode the '?' character.

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

Converting a URL that you receive from user input is sometimes tricky. For example, a user may enter an address as "17th st. & 8th ave." Generally, you should construct your URL from its parts, treating any user input as literal characters.

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