A. API Key and Signature

To use the Zerista API you need to have an application key. We use this key to authenticate your requests and track API usage. A single API key is associated with a Zerista account; therefore, you must first have a Zerista account to get an API key. A key consists of an integer id and a string signing key. For the examples in this section, we will use the key_id 123456 and the key SEFOaW5Wc0drbHM1Z3JoNw==
Every API request must be signed. First, add your key_id to the request’s parameters.

first_name=rufus&last_name=kanarowski&key_id=123456

Next, you must generate the signing string and hash it with the MD5 algorithm (hexadecimal output) to generate the request’s signature. This is done with the following steps:

1. Concatenate all the HTTP parameters in the form = keeping the GET and POST parameter lists separate.
2. Sort the GET and POST key-value pair lists separately.
3. Concatenate the GET and POST key-value lists together.
4. Concatenate the signing key to the string. NOTE: This is to be done before any keys or values are URI encoded. For example, the open square bracket character ‘[' should not be encoded as '%5B'

The form of the signing string:

<key-value-pair>  ::= <key>=<value>
<get-params>      ::= <key-value-pair><key-value-pair>...
<post-params>     ::= <key-value-pair><key-value-pair>...
<sigining-string> ::= <get-params><post-params><signing-key>

Here is an example of a signing string:

first_name=rufuskey_id=123456last_name=kanarowskiSEFOaW5Wc0drbHM1Z3JoNw==

After hashing with MD5, we get

61bd2da638caba60ffb2ea89a08e3b8d

Finally, add the signature to the request’s parameters, and your request is ready to be submitted:

POST /user?first_name=rufus&last_name=kanarowski&key_id=123456&sig=61bd2da638caba60ffb2ea
89a08e3b8d

Longer Test Example

Key id: 3, Key String: 5vucuk6NMjrDhkP6WBVHCA==

Initial request:

NOTE: The password field (user[mapbuzz_auth_attributes][password]) specified in the example below is an “optional” field. If you plan on passing a password as a parameter, please communicate with Zerista beforehand. Also, do NOT pass a password parameter while making a PUT request as it will update the user’s existing password on the system.

POST /user?format=atom&user[last_name]=Wellton&user[mapbuzz_auth_attributes][password]=my
password&user[mapbuzz_auth_attributes][email]=sandrine@mapbuzz.com&user[mapbuzz_auth_attr
ibutes][email_confirmation]=sandrine@mapbuzz.com&user[first_name]=Sandrine&user[account_a
ttributes][account_name]=sandrine&key_id=3

Signing String:

format=atomkey_id=3user[account_attributes][account_name]=sandrineuser[first_name]=Sandri
neuser[last_name]=Welltonuser[mapbuzz_auth_attributes][email]=sandrine@mapbuzz.comuser[ma
pbuzz_auth_attributes][email_confirmation]=sandrine@mapbuzz.comuser[mapbuzz_auth_attribut
es][password]=mypassword5vucuk6NMjrDhkP6WBVHCA==

Signature:

7c3dcce0a03120c0ec1b61fca95f0cf3

Final Request:

POST /user?format=atom&user[last_name]=Wellton&user[mapbuzz_auth_attributes][password]=my
password&user[mapbuzz_auth_attributes][email]=sandrine@mapbuzz.com&user[mapbuzz_auth_attr
ibutes][email_confirmation]=sandrine@mapbuzz.com&user[first_name]=Sandrine&user[account_a
ttributes][account_name]=sandrine&key_id=3&sig=7c3dcce0a03120c0ec1b61fca95f0cf3

Signature Testing

You can test your signature algorithm by using this URL:

http://{your-subdomain}.zerista.com/signature_test

You may GET, POST, or PUT to this URL. It will give you debugging feedback including the expected signing string and whether or not your signature is correct.

Pseudo Code for Generating Signatures

signingKeyId   := your signing key ID
signingKey     := your string signing key
getParameters  := HashTable of HTTP GET parameters
postParameters := HashTable of HTTP POST parameters

ADD KEY:"key_id" VALUE:signingKeyId TO getParameters

getStrings  = NEW Array OF Strings
postStrings = NEW Array OF Strings

FOREACH key,value IN getParameters DO
    newString = key + "=" + value
    ADD newString TO getStrings
END

FOREACH key,value IN postParameters DO
    newString = key + "=" + value
    ADD newString TO postStrings
END

SORT getStrings
SORT postStrings

signingString = NEW String

FOR string IN getStrings DO
    CONCATENATE string TO signingString
END

FOR string IN postStrings DO
    CONCATENATE string TO signingString
END

CONCATENATE signingKey TO signingString

signature = MD5 OF signingString IN HEXIDECIMAL

ADD KEY:"sig" VALUE:signature TO getParameters

# You can now build your HTTP request from your hash tables of GET
# and POST parameters.