Getting Started

From ePrize Developers Wiki

Current revision

The secret of getting ahead is getting started. The secret of getting started is breaking your complex overwhelming tasks into small manageable tasks, and then starting on the first one.

- Mark Twain

Hello, Developer. If you are reading this, you are itching to get started building your interactive promotion. First, please accept our warm Welcome.

In order to create a promotion using BReWS, you don't need much:

1. You need to be a programmer, or be friends with one, well versed in Internet (HTTP) technologies
2. You need to be able to deploy your application in an environment connected to the Internet so that it can communicate with our services
3. You need to have an API Key

Once you have all that, you are ready to get started.

Getting Help

First, start with this site. Documentation on services available, call mechanisms, and debugging can be found here. Good starting points are this page, especially the #Your First Calls section, and the FAQ.

Second, make use of the Webservices Mailing List. You can interact with other BReWS users, including the engineering team that builds and maintains it.

Third, if you are really in a pickle, call your primary HelloWorld contact. They can get you the additional help you need.

What You'll Start With

When you're ready to get started, HelloWorld will send you information on your API key, including URIs to use for testing and for the live deployment. In the following examples, we'll use a fictional URI, http://test.url.api.eprize.com/v1/eprize/ews12/, which mimics the URIs you'd use. The hostname portion contains a client identifier, in this case: test, and a platform identifier, in this case: url.

You'll receive something similar to this: http://eprize.review.api.eprize.com, which is the hostname for HelloWorld's review environment.

In the fictional URI, "eprize/ews12" is the API Key, and you will use the hostname and API Key together with the documentation to build calls to the correct resources.

In addition to URIs, you'll also receive instructions for authenticating to the review environment, which is password protected. The live environment has no password protection.

Your First Calls

Below are examples of using a command line utility, curl, to access a test promotion and exercise many of the fundamental promotion calls available. Each call uses a fictional URI, http://test.url.api.eprize.com/v1/eprize/ews12/, to demonstrate the raw HTTP Request and Response to each call.

Using these calls as a model, you can construct calls that use your promotion URI using your programming language of choice. For example, in the first communication test example below which demonstrates a simple GET request returning an expected Hello World! message, you could construct an ActionScript block to make the same call that might look something like this:

import flash.events.HTTPStatusEvent;
import flash.events.IOErrorEvent;
 
var myTestUrl:URLRequest = new URLRequest(
    "http://test.url.api.eprize.com/v1,t/eprize/ews12/test/communication");
var myLoader:URLLoader = new URLLoader();
var myXML:XML;
 
function onTestCommunicationLoaded(event:Event):void
{
    myXML = new XML(event.target.data);
    trace(myXML.toXMLString());
}
 
function handleStatus(event:HTTPStatusEvent):void
{
    trace(event.status);       
}
 
function handleError(event:IOErrorEvent):void
{
    trace(event);     
}
  
myLoader.addEventListener(Event.COMPLETE, onTestCommunicationLoaded); 
myLoader.addEventListener(HTTPStatusEvent.HTTP_STATUS, handleStatus) ;
myLoader.addEventListener(IOErrorEvent.IO_ERROR, handleError);
myLoader.load(myTestUrl);

Verify API Key and basic communication with HelloWorld is working

$ curl -i -X GET -H "Accept: text/xml" \
  http://test.url.api.eprize.com/v1/eprize/ews12/test/communication
HTTP 200 OK
Cache-Control: no-cache
Date: Thu, 25 Jun 2009 13:59:01 GMT
Pragma: no-cache
Server: POE HTTPD Component/0.09 (5.008008)
Content-Length: 79
Content-Type: text/xml; charset=utf-8
Expires: Thu, 25 Jun 2009 13:59:01 GMT
X-Cache: MISS from broker.int.eprize.net
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Connection: close

<?xml version="1.0" encoding="UTF-8" ?>
<result ver="1.0">Hello world</result>

Create CAPTCHA

$ curl -i -X POST -H "Accept: text/xml" -H "Content-Length: 0" \
  http://test.url.api.eprize.com/v1/eprize/ews12/captcha
HTTP 201 Created
Cache-Control: no-cache
Date: Thu, 25 Jun 2009 14:05:47 GMT
Pragma: no-cache Location: \
    http://test.url.api.eprize.com/v1/eprize/ews12/captcha/duck.f.1800-a8fdc-...
Server: POE HTTPD Component/0.09 (5.008008)
Content-Length: 18
Content-Type: text/xml; charset=utf-8
Expires: Thu, 25 Jun 2009 14:05:47 GMT
X-Cache: MISS from broker.int.eprize.net
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Connection: close

<result>1</result>

Fetch CAPTCHA Challenge Image

(use web browser to see image: curl -X GET is unfriendly)

$ curl -i -X GET \
  http://test.url.api.eprize.com/v1/eprize/ews12/captcha/duck.f.1800-a8fdc-...
HTTP 200 OK
Cache-Control: no-cache
Date: Thu, 25 Jun 2009 14:07:02 GMT
Pragma: no-cache
Server: POE HTTPD Component/0.09 (5.008008)
Content-Length: 872
Content-Type: image/png
Expires: Thu, 25 Jun 2009 14:07:02 GMT
X-Cache: MISS from broker.int.eprize.net
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Connection: close

[872 bytes of PNG image]

Lookup consumer that has not registered yet (non-existent profile)

$ curl -i -X GET -H "Accept: text/xml" \
  "http://test.url.api.eprize.com/v1/eprize/ews12/profile(email)/john.smith@sample.com"
HTTP 404 Not Found
Cache-Control: no-cache
Date: Thu, 25 Jun 2009 14:11:27 GMT
Pragma: no-cache
Server: POE HTTPD Component/0.09 (5.008008)
Content-Length: 81
Content-Type: text/xml; charset=utf-8
Expires: Thu, 25 Jun 2009 14:11:27 GMT
X-Cache: MISS from broker.int.eprize.net
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Connection: close

<?xml version="1.0" encoding="UTF-8" ?>
<result>
  <status>0</status>
</result>

Register the consumer (the specific fields are configurable)

This example has email, confirm_email and address enabled. CAPTCHA is not used in this example. If the request comes from a client's trusted servers there isn't any need because HelloWorld assumes the client has verified the registration.

$ curl -i -X POST -H "Accept: text/xml" \
  -demail=john.smith@sample.com \
  -daddress1='100 Main' \
  -dcity='New York' \
  -dstate=NY \
  -dzip=11201 \
  http://test.url.api.eprize.com/v1/eprize/ews12/profiles
HTTP 400 Bad Request
Cache-Control: no-cache
Date: Thu, 25 Jun 2009 14:14:37 GMT
Pragma: no-cache
Server: POE HTTPD Component/0.09 (5.008008)
Content-Length: 148
Content-Type: text/xml; charset=utf-8
Expires: Thu, 25 Jun 2009 14:14:37 GMT
X-Cache: MISS from broker.int.eprize.net
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Connection: close

<?xml version="1.0" encoding="UTF-8" ?>
<result>
  <input_error>
    <name>confirm_email</name>
    <error>NULL</error>
  </input_error>
</result>

Consumer forgot to enter confirm_email—new register call with fixed fields.

HelloWorld verifies all fields, but client-side verification of fields will reduce call counts and generally improve performance.

$ curl -i -X POST -H "Accept: text/xml" \
  -demail=john.smith@sample.com \
  -dconfirm_email=john.smith@sample.com \
  -daddress1='100 Main' \
  -dcity='New York' \
  -dstate=NY \
  -dzip=11201 \
  http://test.url.api.eprize.com/v1/eprize/ews12/profiles
HTTP 201 Created
Cache-Control: no-cache
Date: Thu, 25 Jun 2009 14:14:58 GMT
Pragma: no-cache
Location: http://test.url.api.eprize.com/v1/eprize/ews12/profile/1
Server: POE HTTPD Component/0.09 (5.008008)
Content-Length: 200
Content-Type: text/xml; charset=utf-8
Expires: Thu, 25 Jun 2009 14:14:58 GMT X-Cache: MISS from broker.int.eprize.net
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Connection: close

<?xml version="1.0" encoding="UTF-8" ?>
<result>
  <profile>
    <id>1</id>
    <country>US</country>
    <first_name></first_name>
    <locale></locale>
    <state>NY</state>
  </profile>
</result>

Lookup consumer that has registered

Not necessary if you have saved the registration call response. Note "Location" header is same as in registration call.

$ curl -i -X GET -H "Accept: text/xml" \
  "http://test.url.api.eprize.com/v1/eprize/ews12/profile(email)/john.smith@sample.com"
HTTP 303 See Other
Cache-Control: no-cache
Date: Thu, 25 Jun 2009 14:17:05 GMT
Pragma: no-cache
Location: http://test.url.api.eprize.com/v1/eprize/ews12/profile/1
Server: POE HTTPD Component/0.09 (5.008008)
Content-Length: 200
Content-Type: text/xml; charset=utf-8
Expires: Thu, 25 Jun 2009 14:17:05 GMT
X-Cache: MISS from broker.int.eprize.net
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Connection: close

<?xml version="1.0" encoding="UTF-8" ?>
<result>
  <profile>
    <id>1</id>
    <country>US</country>
    <first_name></first_name>
    <locale></locale>
    <state>NY</state>
  </profile>
</result>

Lookup consumer by profile id, aka canonical profile resource.

This is the "Location" header from a registration or profile key lookup call.

$ curl -i -X GET -H "Accept: text/xml" \
  http://test.url.api.eprize.com/v1/eprize/ews12/profile/1
HTTP 200 OK
Cache-Control: no-cache
Date: Thu, 25 Jun 2009 14:17:28 GMT
Pragma: no-cache
Server: POE HTTPD Component/0.09 (5.008008)
Content-Length: 200
Content-Type: text/xml; charset=utf-8
Expires: Thu, 25 Jun 2009 14:17:28 GMT
X-Cache: MISS from broker.int.eprize.net
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Connection: close
 
<?xml version="1.0" encoding="UTF-8" ?>
<result>
  <profile>
    <id>1</id>
    <country>US</country>
    <first_name></first_name>
    <locale></locale>
    <state>NY</state>
  </profile>
</result>

Award an instant-win play token to a consumer.

$ curl -i -X POST -H "Accept: text/xml" \
  -dprofile="http://test.url.api.eprize.com/v1/eprize/ews12/profile/1" \
  http://test.url.api.eprize.com/v1/eprize/ews12/game/36191b82.../tokens
HTTP 201 Created
Content-Type: text/xml
Date: Thu, 25 Jun 2009 14:21:11 GMT
Location: \
    http://test.url.api.eprize.com/v1/eprize/ews12/game/36191b82.../token/1b5d340910e6b721
Accept-Ranges: bytes
Server: Noelios-Restlet-Engine/1.1..2
X-Cache: MISS from broker.int.eprize.net
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Connection: close

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <token>
    <id>1b5d340910e6b721</id>
    <profile>1</profile>
    <game>36191b82-7747-102c-bf89-93727f294d11</game>
    <redeemed>false</redeemed>
  </token>
</result>

Lookup the token that was awarded.

$ curl -i -X GET -H "Accept: text/xml" \
  http://test.url.api.eprize.com/v1/eprize/ews12/game/36191b82.../token/1b5d340910e6b721
HTTP 200 OK
Content-Type: text/xml
Date: Thu, 25 Jun 2009 14:22:35 GMT
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Accept-Ranges: bytes
Server: Noelios-Restlet-Engine/1.1..2
X-Cache: MISS from broker.int.eprize.net
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Connection: close

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <token>
    <id>1b5d340910e6b721</id>
    <profile>1</profile>
    <game>36191b82-7747-102c-bf89-93727f294d11</game>
    <redeemed>false</redeemed>
  </token>
</result>

Redeem (play) the token that was awarded. This example shows a lose scenario.

Curl needs the "Content-Length" header because it doesn't automatically handle empty POSTs.

$ curl -i -X POST -H "Accept: text/xml" -H "Content-Length: 0" \
  http://test.url.api.eprize.com/v1/eprize/ews12/game/36191b82.../token/1b5d340910e6b721
HTTP 200 OK
Content-Type: text/xml
Date: Thu, 25 Jun 2009 14:24:16 GMT
Accept-Ranges: bytes
Server: Noelios-Restlet-Engine/1.1..2
X-Cache: MISS from broker.int.eprize.net
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Connection: close

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <token>
    <id>1b5d340910e6b721</id>
    <profile>1</profile>
    <game>36191b82-7747-102c-bf89-93727f294d11</game>
    <redeemed>true</redeemed>
    <awards/>
  </token>
</result>

Attempting to redeem a token twice results in a not found error.

$ curl -i -X POST -H "Accept: text/xml" -H "Content-Length: 0" \
  http://test.url.api.eprize.com/v1/eprize/ews12/game/36191b82.../token/1b5d340910e6b721
HTTP 404 Not Found
Content-Type: text/xml
Date: Thu, 25 Jun 2009 14:24:39 GMT
Accept-Ranges: bytes
Server: Noelios-Restlet-Engine/1.1..2
X-Cache: MISS from broker.int.eprize.net
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Connection: close

<?xml version="1.0" encoding="UTF-8"?>
<result/>

Award another instant-win play.

$ curl -i -X POST -H "Accept: text/xml" \
  -dprofile="http://test.url.api.eprize.com/v1/eprize/ews12/profile/1" \
  http://test.url.api.eprize.com/v1/eprize/ews12/game/36191b82.../tokens
HTTP 201 Created
Content-Type: text/xml
Date: Thu, 25 Jun 2009 14:45:22 GMT
Location: http://test.url.api.eprize.com/v1/eprize/ews12/game/36191b82.../token/6a85a59b4fed93db
Accept-Ranges: bytes
Server: Noelios-Restlet-Engine/1.1..2
X-Cache: MISS from broker.int.eprize.net
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Connection: close

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <token>
    <id>6a85a59b4fed93db</id>
    <profile>1</profile>
    <game>36191b82-7747-102c-bf89-93727f294d11</game>
    <redeemed>false</redeemed>
  </token>
</result>

Redeem the token. This is a win scenario.

$ curl -i -X POST -H "Accept: text/xml" -H "Content-Length: 0" \
  http://test.url.api.eprize.com/v1/eprize/ews12/game/36191b82.../token/6a85a59b4fed93db
HTTP 200 OK
Content-Type: text/xml
Date: Thu, 25 Jun 2009 14:45:36 GMT
Accept-Ranges: bytes
Server: Noelios-Restlet-Engine/1.1..2
X-Cache: MISS from broker.int.eprize.net
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Connection: close

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <token>
    <id>6a85a59b4fed93db</id>
    <profile>1</profile>
    <game>36191b82-7747-102c-bf89-93727f294d11</game>
    <redeemed>true</redeemed>
    <awards>
      <prizes>
        <prize>/v1/eprize/ews12/game/36191b82.../prize/36191b78...</prize>
      </prizes>
    </awards>
  </token>
</result>

Lookup the prize won. This information can be cached—prizes won't change unless reconfigured by request.

$ curl -i -X GET -H "Accept: text/xml" \
  http://test.url.api.eprize.com/v1/eprize/ews12/game/36191b82.../prize/36191b78...
HTTP 200 OK
Content-Type: text/xml
Date: Thu, 25 Jun 2009 14:46:23 GMT
Vary: Accept-Charset, Accept-Encoding, Accept-Language, Accept
Accept-Ranges: bytes
Server: Noelios-Restlet-Engine/1.1..2
X-Cache: MISS from broker.int.eprize.net
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Connection: close

<?xml version="1.0" encoding="UTF-8"?>
<result>
  <prize>
    <id>36191b78-7747-102c-bf89-93727f294d11</id>
    <description>Fabulous Pink Pony</description>
    <game>36191b82-7747-102c-bf89-93727f294d11</game>
  </prize>
</result>