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.
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.
The API supports both JSON and XML responses. It defaults to JSON, but XML can be requested by using the Accept HTTP header:
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.
To get the CanonicalizedParameters string, follow these steps:
- Collect all GET parameters in a key-value array.
- URL encode all the keys and values.
- Sort the array by key.
- Convert the key/value pairs into one string:
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.
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
|1.||Format the request timestamp to ISO8601. This will become the
|3.||Create the CanonicalizedParameters string, as described before.||
|4.||Get the full resource string. This is the URL with protocol and servername, but excluding the query string.||
|5.||Combine all strings into one string to sign.||GET
|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.||
|8.||Add the Authorization HTTP header to your request||