Menu
Product Advertising API
Developer Guide (API Version 2013-08-01)

Authenticating REST Requests

This section describes how to create a signature. The Product Advertising API supports only Signature Version 2. You can also use the Product Advertising API Scratchpad to generate sample code for requests and responses. For more information, see Using the Product Advertising API Scratchpad.

To create the signature

  1. Create the canonicalized query string that you need later in this procedure:

    1. Sort the UTF-8 query string components by parameter name with natural byte ordering.

      The parameters can come from the GET URI or from the POST body (when Content-Type is application/x-www-form-urlencoded).

    2. URL encode the parameter name and values according to the following rules:

      • Do not URL encode any of the unreserved characters that RFC 3986 defines.

        These unreserved characters are A-Z, a-z, 0-9, hyphen ( - ), underscore ( _ ), period ( . ), and tilde ( ~ ).

      • Percent encode extended UTF-8 characters in the form %XY%ZA.

      • Percent encode the space character as %20 (and not +, as common encoding schemes do).

      • Percent encode all other characters with %XY, where X and Y are hex characters 0-9 and uppercase A-F.

        Perl Note:

        The commonly used URI::Escape CPAN module uses RFC 2396. This has five additional reserved characters: asterisk ( * ), left and right parenthesis ( ( and ) ), single quote ( ‘ ) and exclamation ( ! ). To follow RFC 3986 use:

        Copy
        URI::Escape::uri_escape( $parameter_value, "^A-Za-z0-9\-_.~" )

        Java Note:

        URLEncoder uses + for space, and won’t encode asterisk ( * ) , and encodes tilda ( ~ ) when not necessary. To follow RFC 3986 use:

        Copy
        URLEncoder.encode(value, UTF_8_Encoding).replace("+", "%20").replace("*", "%2A").replace("%7E", "~");

        C# Note:

        Use uppercase hex characters.

      Tip

      Currently all Product Advertising API service parameter names use unreserved characters, so you don't need to encode them. However, you might want to include code to handle parameter names that use reserved characters, for possible future use.

    3. Separate the encoded parameter names from their encoded values with the equals sign ( = ) (ASCII character 61), even if the parameter value is empty.

    4. Separate the name-value pairs with an ampersand ( & ) (ASCII code 38).

  2. Create the string to sign according to the following pseudo-grammar (the "\n" represents an ASCII newline).

    Copy
    StringToSign = HTTPVerb + "\n" + ValueOfHostHeaderInLowercase + "\n" + HTTPRequestURI + "\n" + CanonicalizedQueryString <from the preceding step>

    The HTTPRequestURI component is the HTTP absolute path component of the URI up to, but not including, the query string. If the HTTPRequestURI is empty, use a forward slash ( / ).

    Note

    HTTPRequestURI is always “/onca/xml” for Product Advertising API. HTTPVerb is either GET or POST.

  3. Calculate an RFC 2104-compliant HMAC with the string you just created, your AWS secret access key as the key, and SHA256 as the hash algorithm.

    For more information, see RFC2104.

  4. Convert the resulting value to base64.

  5. Use the resulting value as the value of the Signature request parameter.

The final signature you send in the request must be URL encoded as specified in RFC 3986. If your toolkit URL encodes your final request, then it handles the required URL encoding of the signature. If your toolkit doesn't URL encode the final request, then make sure to URL encode the signature before you include it in the request.

Important

Verify the signature is URL encoded only once. A common mistake is to URL encode it manually during signature formation, and then again when the toolkit URL encodes the entire request.

For examples of signed requests, see Example REST Requests.