Basics

Endpoint location

The Sooqr API is hosted on https://api.sooqr.com. All API calls should use SSL/TLS. TLS1.2 is supported and preferred over older TLS versions.

API versions

The current API version is v1 and it is hosted on https://api.sooqr.com/v1. You always have to specify the API version you would like to use. When new versions are created, check the Changelog for breaking changes before upgrading.

Response formats

The API supports both JSON and XML responses. It defaults to JSON, but XML can be requested by using the Accept HTTP header:

Accept: application/xml

Authentication

Most API calls require authentication.

The Sooqr REST API uses the standard HTTP Authorization header to pass authentication information. Under the Sooqr authentication scheme, the Authorization header has the following form:

Authorization: Sooqr AccessKeyId:Signature

Developers can generate an access key ID and secret access key from the mySooqr backend. For request authentication, the AccessKeyId element identifies the access key ID that was used to compute the signature and, indirectly, the developer making the request.

The Signature element is the RFC 2104 HMAC-SHA1 of selected elements from the request, and so the Signature part of the Authorization header will vary from request to request. If the request signature calculated by the system matches the Signature included with the request, the requester will have demonstrated possession of the secret access key. The request will then be processed under the identity, and with the authority, of the developer to whom the key was issued.

Following is pseudogrammar that illustrates the construction of the Authorization request header. (In the example, \n means the Unicode code point U+000A, commonly called newline).

Authorization = "Sooqr" + " " + AccessKeyId + ":" + Signature;

Signature = Base64( HMAC-SHA1( YourSecretAccessKeyID, UTF-8-Encoding-Of( StringToSign ) ) );

StringToSign = HTTP-Verb + "\n" +
    CanonicalizedParameters + "\n" +
    Date + "\n" +
    CanonicalizedResource;

CanonicalizedParameters = <described below>

CanonicalizedResource = <HTTP-Request-URI, from the protocol name up to the query string>;

HMAC-SHA1 is an algorithm defined by RFC 2104 - Keyed-Hashing for Message Authentication . The algorithm takes as input two byte-strings, a key and a message. Use your Secret access key as the key, and the UTF-8 encoding of the StringToSign as the message. The output of HMAC-SHA1 is also a byte string, called the digest. The Signature request parameter is constructed by Base64 encoding this digest.

CanonicalizedParameters

To get the CanonicalizedParameters string, follow these steps:

  1. Collect all GET parameters in a key-value array.
  2. URL encode all the keys and values.
  3. Sort the array by key.
  4. Convert the key/value pairs into one string: key1=value1&key2=value2

Timestamp

The timestamp submitted with your request is used to prevent replay attacks. Therefore, the time should be within 15 minutes of the Sooqr API server time. If the time difference is too big, the server will return an error code 500 with the message The Date for this request must be within 15 minutes of our system time.

Example

This example is based on this HTTP request:

GET https://api.sooqr.com/v1/search/100506/1?q=maxi+dress&qWildcard=0&fl=id,title HTTP/1.1
Host: api.sooqr.com
Authorization: Sooqr a1a1a1a1a1a1a1a1:R16je690YVm38AkyjeF0r6IyYEM=
X-Sqr-Date: Thu, 24 Dec 2015 12:47:28 GMT
Accept: application/json

Our key identifier is a1a1a1a1a1a1a1a1 and our (fictional) secret is b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2b2

# Description Result
1. Format the request timestamp to ISO8601. This will become the Date parameter in your string to sign. 20151224T124728Z
2. Add the date or x-sqr-date HTTP header to the request as a verbose string. Thu, 24 Dec 2015 12:47:28 GMT
3. Create the CanonicalizedParameters string, as described before. fl=id,title&q=maxi+dress&qWildcard=0
4. Get the full resource string. This is the URL with protocol and servername, but excluding the query string. https://api.sooqr.com/v1/search/100506/1
5. Combine all strings into one string to sign. GET\n
fl=id,title&q=maxi+dress&qWildcard=0\n
20151224T124728Z\n
https://api.sooqr.com/v1/search/100506/1
6. Convert the string to UTF-8 and sign it with your secret key. (Binary result is not shown here)
7. Base64 encode the resulting binary data. R16je690YVm38AkyjeF0r6IyYEM=
8. Add the Authorization HTTP header to your request Authorization: Sooqr a1a1a1a1a1a1a1a1:R16je690YVm38AkyjeF0r6IyYEM=