API

The Promotably API Server

Usage

Cider

Make sure your ~/.lein/profiles.clj has at least:

 $ cat ~/.lein/profiles.clj
 {:user {:plugins [[lein-midje "3.0.0"]
                  [cider/cider-nrepl "0.8.0"]]}}

Database

NOTE: If you are using the devbox/schmetterling repo for a development VM, you don't need to do this.

This server uses PostgreSQL 9.3. If you're looking for a really easy way to run a postgresql database on your mac, checkout postgres.app

Also, the postgresql extension uuid-ossp is required. Once you have your database up, do the following setup:

CREATE USER p_user WITH PASSWORD 'pr0m0';
CREATE DATABASE promotably_dev;
GRANT ALL PRIVILEGES ON DATABASE promotably_dev to p_user;
\c promotably_dev
CREATE EXTENSION "uuid-ossp";
CREATE TABLE migrations(version varchar(255));
GRANT ALL PRIVILEGES ON TABLE migrations TO p_user;

Migrations

API uses drift for migrations.

To run migrations:

lein migrate

To generate a new migration file:

lein create-migration <the name of the migration>

This places a migration file in the src/migrations directory

AWS Credentials

Before you can run the server or the integration tests you need AWS credentials. Once you have an id and key you can save the credentials to ~/.aws/credentials:

[promotably]
aws_access_key_id=<ID>
aws_secret_access_key=<KEY>

Running the Server

lein run

Testing

Unit Testing

ENV=test lein midje "api.unit.*"

Integration Testing

KINESIS_A=dev-PromotablyAPIEvents RDS_HOST=localhost RDS_PORT=5432 RDS_USER=p_user RDS_DB_NAME=promotably_dev RDS_PW=pr0m0 REDIS_HOST=localhost REDIS_PORT=6379 ENV=integration lein midje "api.integration.*"

Integration testing depends on AWS credentials as per doc.

Interactive Testing

Before you can begin testing conditions you will want to make sure you are not in the control group. First you need to generate a test ID:

lein test-uuid

Once you have this new uuid, open up your browser and edit the cookie promotably for api-staging.promotably.com or whatever domain your are testing against.

Development

Use the usual in emacs: cider-jack-in. Open core.clj and load the file in cider. Then eval the desired lines at the bottom of the file:

  (System/setProperty "ENV" "dev")
  (System/setProperty "ENV" "localdev")
  (System/getProperty "ENV")

  (prn api.system/current-system)
  (go {:port 3000 :repl-port 55555})
  (stop)

Request Signing

Authenticated requests to the Promotably API include a cryptographic signature to allow the API to validate requests. The reqestor includes an HTTP header ('Promotably-Auth') that has been computed as follows.

First, the requestor computes a cryptographic hash (an HMAC) of the request body using the SHA1 algorithm.

body-hash = HEXDIGEST(HMAC(request body))

The requestor then computes a string of header lines to be included in the signature string. The included header lines are sorted alphabetically, and put in Header-Name: Header-Value + newline ("\n") form, and concatenated together. For example, if the requestor wants to include the User-Agent header and the Accept header, the string might be:

Accept: /\nUser-Agent: curl/7.10.6 (i386-redhat-linux-gnu) libcurl/7.10.6 OpenSSL/0.9.7a ipv6 zlib/1.1.4\n

Next, the requestor computes a string of query string fields to be included in the signature string. The included query string field names are sorted alphabetically, and put in field-name=field-value

ampersand ("&") form, and concatenated together. For example, if the requestor's URL looked like:

http://api.promotably.com/v1/track?site-id=26b28c70-2144-4427-aee3-b51031b08426&event-name=_trackProductView&product-id=WW1

Then, the string might be:

event-name=_trackProductView&product-id=WW1&site-id=26b28c70-2144-4427-aee3-b51031b08426

Note that the requestor need not specify the totality of all query string fields available in the URL; nor any at all, for that matter.

Then the requestor computes a signature string by concatenating the following elements:

0. requestor's site id + newline ("\n")
1. requestor's API secret key + newline ("\n")
2. http host (as presented in HTTP request) + newline ("\n")
3. http verb (as presented in HTTP request) + newline ("\n")
4. request URL (excluding query string, and then percent-encoded) + newline ("\n")
5. datetime in iso8601 format (YYYYMMDDTHHMMSSZ) + newline ("\n")
6. body-hash + newline ("\n").  If no body is present, just newline.
7. signed-header-lines + newline ("\n")
8. signed-query-string-fields + newline ("\n")

A string hexdigest is computed from the signature string:

signature = HEXDIGEST(HMAC(signature-string))

The requestor then constructs a valid authorization value for use in the Promotably-Auth header by concatenating the following strings:

1. "hmac-sha1/" +
2. names (not values) of signed headers, sorted alphabetically and
   separated by commas (",").  Eg., "Accept,User-Agent"
3. "/"
4. names (not values) of signed query string fields, sorted alphabetically and
   separated by commas (",").  Eg., "event-name,product-id,site-id"
5. "/"
6. datetime in iso8601 format (YYYYMMDDTHHMMSSZ)
7. "/"
8. signature (as computed above)

The resulting string is then url encoded, and the value of the Promotably-Auth header is set to the result.

Alternatively, the requestor may append the authorization value as an additional query string parameter. Eg., "&promotably-auth=..." If so, the uri used in computation of the signature string (above) does not include the promotably-auth parameter. If transmitted in the query string, this query parameter must the be the last one present in the query string.

Tracking API

As shoppers explore and interact with our customers' e-commerce sites, their behvaior reveals intent and other information that Signal96 uses for product recommendation, dynamic promotion creation and display, and other uses. This shopper behavior is transmitted to our tracking API by a javascript library residing on the e-commerce site.

Tracking endpoint

SUMMARY

JSONP endpoint for tracking shopper interaction with customer e-commerce sites.

ENDPOINT: GET https://api.promotably.com/v1/track

AUTHENTICATION: signature

RESPONSE STATUS: 200

RESPONSE BODY: none

QUERY PARAMETERS

* site-id - Required.  String.  Identifies customer site.
* event-type - Required.  String.  Event name.
* <event type dependent> - See below.