Getting Started

From ePrize Developers Wiki

(Difference between revisions)
Jump to: navigation, search
(→Redeem (play) the token that was awarded. This example shows a lose scenario.)
(→Attempting to redeem a token twice results in a not found error.)
Line 322: Line 322:
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Via: 1.0 broker.int.eprize.net (squid/3.1.0.6)
Connection: close
Connection: close
-
 
+
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<result/>
<result/>

Revision as of 15:12, 5 August 2009

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.


Contents

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 ePrize contact. They can get you the additional help you need.

Your First Calls

Below is an example of using a command line utility, curl, to access a test promotion installed on a staging server.

Verify API Key and basic communication with ePrize is working 

$ curl -i -X GET -H "Accept: text/xml" \
  http://test.url.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>

Fetch Games

(the games will not change unless client reconfigures--game URLs can be hardcoded to reduce API calls) 

$ curl -i -X GET -H "Accept: text/xml" \
  http://test.url.eprize.com/v1/eprize/ews12/games
HTTP 200 OK
Content-Type: text/xml
Date: Thu, 25 Jun 2009 14:05:27 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>
     <game href="/v1/eprize/ews12/game/36191b82-7747-102c-bf89-93727f294d11" type="iw"/>
</result>

Create CAPTCHA 

$ curl -i -X POST -H "Accept: text/xml" -H "Content-Length: 0" \
  http://test.url.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.eprize.com/v1/eprize/ews12/captcha/duck.f.1800-a8fdc-15b7-6ed9321.0e717e8676619da8dd1a39614a703beb
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.eprize.com/v1/eprize/ews12/captcha/duck.f.1800-a8fdc-15b7-6ed9321.0e717e8676619da8dd1a39614a703beb
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.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 ePrize 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.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.

ePrize 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.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.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.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.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.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.eprize.com/v1/eprize/ews12/profile/1" \
  http://test.url.eprize.com/v1/eprize/ews12/game/36191b82-7747-102c-bf89-93727f294d11/tokens
HTTP 201 Created
Content-Type: text/xml
Date: Thu, 25 Jun 2009 14:21:11 GMT
Location: http://test.url.eprize.com/v1/eprize/ews12/game/36191b82-7747-102c-bf89-93727f294d11/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.eprize.com/v1/eprize/ews12/game/36191b82-7747-102c-bf89-93727f294d11/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.eprize.com/v1/eprize/ews12/game/36191b82-7747-102c-bf89-93727f294d11/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.eprize.com/v1/eprize/ews12/game/36191b82-7747-102c-bf89-93727f294d11/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.eprize.com/v1/eprize/ews12/profile/1" \
  http://test.url.eprize.com/v1/eprize/ews12/game/36191b82-7747-102c-bf89-93727f294d11/tokens
HTTP 201 Created
Content-Type: text/xml
Date: Thu, 25 Jun 2009 14:45:22 GMT
Location: http://test.url.eprize.com/v1/eprize/ews12/game/36191b82-7747-102c-bf89-93727f294d11/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.eprize.com/v1/eprize/ews12/game/36191b82-7747-102c-bf89-93727f294d11/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-7747-102c-bf89-93727f294d11/prize/36191b78-7747-102c-bf89-93727f294d11</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.eprize.com/v1/eprize/ews12/game/36191b82-7747-102c-bf89-93727f294d11/prize/36191b78-7747-102c-bf89-93727f294d11
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>
Retrieved from "https://code.helloworld.com/wiki/index.php/Getting_Started"
Personal tools