Access Keys (API)

The Enalyzer system contains various resources e.g. surveys, launches, reports, respondents etc. The Enalyzer REST API provides a structured view of the various entities and the connections between them. The API is accessed via HTTPS and is available at the base address https://api.enalyzer.com/.

Overview of the API functions

The current API implementation supports the following operations

Projects

HTTP Verb

URI pattern

Function

GET

/projects

Retrieve a list of all project references that can be accessed by the given key

GET

/projects/(id)/launches

Retrieve a list of launches for the specific project with identifier id

GET

/projects/(id)/statistics

Retrieve survey completion statistics for the project id

GET

/projects/(id)/filters

Retrieve a list of filters for the survey id

Launches

HTTP Verb

URI pattern

Function

GET

/launches

Retrieve a list of all launces that can be accessed by the given key

POST

/launches/(id)/respondents

Invites a respondent to the given launch

Filters

HTTP Verb

URI pattern

Function

GET

/filters

Retrieve a list of all filters that can be accessed by the given key

 

API - signing and authenticating the request

The Enalyzer API requires the caller to authenticate the call by signing the URL using a HMAC MD5 signature. Authentication information is passed directly on the URL to facilitate embedding requests directly in web pages and sharing requests. This authentication scheme is currently used also by Amazon Web Services and the Google Maps API, so code examples are abundant on the web.

Sequence

The following sequence should be followed when making requests. Each step is detailed below.

  1. Create the query
  2. Specify your API AccessKey (48 bit / 6 char value)
  3. Specify an expiration time for the query
  4. Sign it with your signature (2048 bit secret key)
  5. Place the data in an HTTP request

 

 

 

Constructing the query string

Build the request path by identifying the host and resource to access. If the call requires any URI parameters add these. Make sure any parameters are safely URI encoded. Example (accessing statistics for a project with id 12345):

/projects/12345/statistics

Back to menu

 

 

 

Specify your API Access key

Resources are accessed by making an https query addressing the requested resource. The API AccessKey is a key that identifies you as the caller, equivalent to a username. Include your API AccessKey as URI parameter named AccessKey. Make sure the access key value is URI encoded before adding the value to the URI string. Example: (Your access key in this example is CF4+RE this in turn is encoded as CF4%2BRE)

/projects/12345/statistics?AccessKey=CF4%2BRE

Back to menu

 

 

 

Specify expiration time

Time is expressed as UNIX time – the number of seconds since January 01, 1970 UTC. Use the current UTC time for making requests. URI Encode the value string and append this to your request as a URI parameter named Expires.

/projects/12345/statistics?AccessKey=CF4%2RE23&Expires=1322517962

The request will be rejected if the expiration time is passed after receiving the request on the server. Some latency is allowed, accounting for minor differences in the time settings between client and server as well as request construction and transfer time.

Back to menu

 

 

 

Sign the request

The request path, any request specific parameters and the AccessKey and Exires parameters must now be signed to create the final URL to call. For this you need your API Secret Key. Secret keys in ESS are 2048 bit randomly generated keys and will thus be much longer than in this example. The request path should start with a slash and should not include the http keyword and domain. Create the Base64 encoded signature and then URL encode the result

Request to sign: projects/12345/statistics?AccessKey=CF4%2RE23&Expires=1322517962Signature: URL-Encode(Base64(HMAC-MD5(APISecretKey, request))) Example result: vjSAMPLENmGa%2ByT272YEAiv4%3D

Back to menu

 

 

 

Make the HTTP request

Append the URL encoded Signature to the request as URI parameter Signature:

https://api.enalyzer.com/projects/12345/statistics?AccessKey=CF44RE23&Expires=1322517962&Signature=vjSAMPLENmGa%2ByT272YEAiv4%3D

The URI is now ready to be passed to the API. Open an HTTP connection and make the request.

Back to menu

Have more questions? Submit a request

Comments

Powered by Zendesk