Getting Started
From ePrize Developers Wiki
(Difference between revisions)
(→Register the consumer (the specific fields are configurable) |
(→Lookup consumer that has registered) |
||
| Line 213: | Line 213: | ||
</result> | </result> | ||
| - | ==== Lookup consumer by profile id, aka canonical profile resource. ====<i>This is the "Location" header from a registration or profile key lookup call.</i> | + | ==== Lookup consumer by profile id, aka canonical profile resource. ==== |
| + | <i>This is the "Location" header from a registration or profile key lookup call.</i> | ||
$ curl -i -X GET -H "Accept: text/xml" \ | $ curl -i -X GET -H "Accept: text/xml" \ | ||
http://test.url.eprize.com/v1/eprize/ews12/profile/1 | http://test.url.eprize.com/v1/eprize/ews12/profile/1 | ||
| Line 227: | Line 228: | ||
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:11, 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:
- You need to be a programmer, or be friends with one, well versed in Internet (HTTP) technologies
- You need to be able to deploy your application in an environment connected to the Internet so that it can communicate with our services
- 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 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>
