Redeem token

From ePrize Developers Wiki

(Difference between revisions)
Jump to: navigation, search
Current revision (14:20, 31 March 2014) (edit) (undo)
 
(14 intermediate revisions not shown.)
Line 1: Line 1:
-
<pre>Request representation:
+
{{RESTfulAPI
-
redeemed:true
+
|crumbs=[[API Home Page]] :: [[Games and Awards]]
 +
|summary=Redeem token and play the instant win game. If the token is valid, the result of this POST will be a win or non-winning message for the instant win game.
-
Response:
+
Win responses will contain a prize identifier in the ''awards'' node. Non-winning responses will not contain a prize identifier and have an empty ''awards'' node. The prize identifiers can be used with the [[Fetch_prize|fetch prize]] resource to find out more information on the prize (such as a description). This can be used to show the user a win or non-win scenario on the front-end.
-
200 OK
+
|resource=/v1/{apikey}/game/{game}/token/{token}
-
Entity body same as GET /v1/{apikey}/game/{game}/token/{token}
+
|methods=POST
 +
|resourceargs='''apikey''': Your [[API Key]].
-
Response if request invalid:
+
'''gameId''': Game Identifier for the Sweepstakes into which the entry will be awarded. (A constant value provided to you by HelloWorld)
-
400 Bad Request
+
-
Entity body describing failed validations
+
-
Response if token already redeemed:
+
'''token''': Token ID retrieved from response from [[Award_token|awarding a token]]
-
405 Conflict
+
|paramsrequired=None
-
Response if limit reached:
+
''Note'': some user have had difficulty with empty POST requests. Adding a random name/value pair (foo=foo) to the request representation can avoid this problem.
-
403 Forbidden
+
}}
-
</pre>
+
-
A successful redemption changes the representation of the token. This shows a redeemed token that resulted the awarding of a prize and a token to another game:
+
== Extra Notes ==
 +
A successful redemption changes the representation of the token. Tokens awarded are available on the [[Fetch_token|fetch token]] resource until they are redeemed.
-
<pre>game:{game},
 
-
profile:{profile},
 
-
redeemed:true,
 
-
awards: [
 
-
prizes: [
 
-
/v1/{apikey}/game/{game1}/prize/{prize},
 
-
...
 
-
],
 
-
tokens: [
 
-
/v1/{apikey}/game/{game2}/token/{token},
 
-
...
 
-
]
 
-
]
 
-
</pre>
 
-
A redeemed token that resulted in no awards:
+
{{RESTfulExample
 +
|title=Redeem Token / Earn Prize
 +
|summary=This demonstrates a good request to redeem a token that exists, and the user wins a prize as a result.
 +
|responsecode=200 OK
 +
|response=<?xml version="1.0" encoding="UTF-8"?>
 +
<result ver="1.0">
 +
<token>
 +
<id>{token}</id>
 +
<profile>{profile}</profile>
 +
<game>{game}</game>
 +
<redeemed>true</redeemed>
 +
<awards>
 +
<prizes>
 +
<prize>/v1/{apikey}/game/{game}/prize/{prize}</prize>
 +
</prizes>
 +
</awards>
 +
</token>
 +
</result>
 +
}}
-
<pre>game:{game},
+
{{RESTfulExample
-
profile:{profile},
+
|title=Redeem Token / Earn New Token
-
redeemed:true,
+
|summary=This demonstrates a good request to redeem a token that exists, and the user wins another token as a result.
-
awards: []
+
|responsecode=200 OK
-
</pre>
+
|response=<?xml version="1.0" encoding="UTF-8"?>
 +
<result ver="1.0">
 +
<token>
 +
<id>{token}</id>
 +
<profile>{profile}</profile>
 +
<game>{game}</game>
 +
<redeemed>true</redeemed>
 +
<awards>
 +
<tokens>
 +
<token>/v1/{apikey}/game/{game}/token/{token2}</token>
 +
</tokens>
 +
</awards>
 +
</token>
 +
</result>
 +
}}
-
The list of awards is immediately available on the resource {profile}/awards. Tokens awarded are available on the resource {profile}/tokens until they are redeemed.
+
{{RESTfulExample
 +
|title=Redeem Token / Earn Nothing :(
 +
|summary=This demonstrates a good request to redeem a token that exists, and the user wins nothing as a result.
 +
|responsecode=200 OK
 +
|response=<?xml version="1.0" encoding="UTF-8"?>
 +
<result ver="1.0">
 +
<token>
 +
<id>{token}</id>
 +
<profile>{profile}</profile>
 +
<game>{game}</game>
 +
<redeemed>true</redeemed>
 +
<awards/>
 +
</token>
 +
</result>
 +
}}
 +
 
 +
{{RESTfulExample
 +
|title=Redeem Token That Doesn't Exist
 +
|summary=This demonstrates a good request to redeem a token that doesn't exist.
 +
|responsecode=404 Not Found
 +
|response=<?xml version="1.0" encoding="UTF-8"?>
 +
<result ver="1.0">
 +
<status>0</status>
 +
</result>
 +
}}
 +
 
 +
{{RESTfulExample
 +
|title=Attempt to Redeem a Token That Has Already Been Redeemed
 +
|responsecode=404 Not Found
 +
|response=<?xml version="1.0" encoding="UTF-8" ?>
 +
<result/>
 +
}}
 +
 
 +
{{RESTfulExample
 +
|title=Attempt to Redeem a Token Beyond Game's Limit
 +
|summary=If tokens are accumulated without redemption it might be possible to attempt to play the game more than is allowed based on the game's limit.
 +
|responsecode=403 Forbidden
 +
|response=<?xml version="1.0" encoding="UTF-8" ?>
 +
<result/>
 +
}}
 +
 
 +
{{RESTfulExample
 +
|title=Invalid Request
 +
|summary=Request is not well-formed or contains other invalid inputs
 +
|responsecode=400 Bad Request
 +
|response=
 +
}}

Current revision

API Home Page :: Games and Awards

Summary

Redeem token and play the instant win game. If the token is valid, the result of this POST will be a win or non-winning message for the instant win game.

Win responses will contain a prize identifier in the awards node. Non-winning responses will not contain a prize identifier and have an empty awards node. The prize identifiers can be used with the fetch prize resource to find out more information on the prize (such as a description). This can be used to show the user a win or non-win scenario on the front-end.

Resource

/v1/{apikey}/game/{game}/token/{token}

Valid Methods

POST

Resource Arguments

Note: resource arguments are always required.

apikey: Your API Key.

gameId: Game Identifier for the Sweepstakes into which the entry will be awarded. (A constant value provided to you by HelloWorld)

token: Token ID retrieved from response from awarding a token

Parameters Required

None

Note: some user have had difficulty with empty POST requests. Adding a random name/value pair (foo=foo) to the request representation can avoid this problem.



Extra Notes

A successful redemption changes the representation of the token. Tokens awarded are available on the fetch token resource until they are redeemed.


Example: Redeem Token / Earn Prize

Summary

This demonstrates a good request to redeem a token that exists, and the user wins a prize as a result.


Response

HTTP Status Code: 200 OK 


<?xml version="1.0" encoding="UTF-8"?>
<result ver="1.0">
  <token>
    <id>{token}</id>
    <profile>{profile}</profile>
    <game>{game}</game>
    <redeemed>true</redeemed>
    <awards>
      <prizes>
        <prize>/v1/{apikey}/game/{game}/prize/{prize}</prize>
      </prizes>
    </awards>
  </token>
</result>


Example: Redeem Token / Earn New Token

Summary

This demonstrates a good request to redeem a token that exists, and the user wins another token as a result.


Response

HTTP Status Code: 200 OK 


<?xml version="1.0" encoding="UTF-8"?>
<result ver="1.0">
  <token>
    <id>{token}</id>
    <profile>{profile}</profile>
    <game>{game}</game>
    <redeemed>true</redeemed>
    <awards>
      <tokens>
        <token>/v1/{apikey}/game/{game}/token/{token2}</token>
      </tokens>
    </awards>
  </token>
</result>


Example: Redeem Token / Earn Nothing :(

Summary

This demonstrates a good request to redeem a token that exists, and the user wins nothing as a result.


Response

HTTP Status Code: 200 OK 


<?xml version="1.0" encoding="UTF-8"?>
<result ver="1.0">
  <token>
    <id>{token}</id>
    <profile>{profile}</profile>
    <game>{game}</game>
    <redeemed>true</redeemed>
    <awards/>
  </token>
</result>


Example: Redeem Token That Doesn't Exist

Summary

This demonstrates a good request to redeem a token that doesn't exist.


Response

HTTP Status Code: 404 Not Found 


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


Example: Attempt to Redeem a Token That Has Already Been Redeemed

Response

HTTP Status Code: 404 Not Found 


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


Example: Attempt to Redeem a Token Beyond Game's Limit

Summary

If tokens are accumulated without redemption it might be possible to attempt to play the game more than is allowed based on the game's limit.


Response

HTTP Status Code: 403 Forbidden 


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


Example: Invalid Request

Summary

Request is not well-formed or contains other invalid inputs




Retrieved from "https://code.helloworld.com/wiki/index.php/Redeem_token"
Personal tools