Award token

From ePrize Developers Wiki

(Difference between revisions)
Jump to: navigation, search
(New page: <pre>Request representation: profile:{profile} Response: 201 Created Location: /v1/{apikey}/game/{game}/token/{token} Entity body same as GET /v1/{apikey}/game/{game}/token/{token} Respo...)
Current revision (14:20, 31 March 2014) (edit) (undo)
 
(16 intermediate revisions not shown.)
Line 1: Line 1:
-
<pre>Request representation:
+
{{RESTfulAPI
-
profile:{profile}
+
|crumbs=[[API Home Page]] :: [[Games and Awards]]
 +
|summary=Award the profile a token, which is used to play the instant win game. The instant win game cannot be played without a valid token. Once a token has been redeemed, it cannot be used again.
-
Response:
+
A token ID returned after a successful token award which will be submitted as a resource argument when redeeming the token for an instant win play.
-
201 Created
+
-
Location: /v1/{apikey}/game/{game}/token/{token}
+
-
Entity body same as GET /v1/{apikey}/game/{game}/token/{token}
+
-
Response if request invalid:
+
Multiple tokens could be accumulated before any are redeemed. Additionally, a profile's tokens can be checked for validity by using the [[Fetch_token|fetch token]] resource.
-
400 Bad Request
+
|resource=/v1/{apikey}/game/{gameid}/tokens
-
Entity body describing failed validations
+
|methods=POST
 +
|resourceargs='''apikey''': Your [[API Key]].
-
Response if limit reached:
+
'''gameId''': Game Identifier for the Sweepstakes into which the entry will be awarded. (A constant value provided to you by HelloWorld)
-
403 Forbidden
+
|paramsrequired='''profile''': Canonical Location of a user profile. See: [[Fetch_profile_by_key|Fetch Profile by Key]].
-
</pre>
+
-
The {profile} value is the canonical URL of the profile that the token should be awarded to.
+
'''event''': Name of an event to create an IW token for (must begin with "api-", e.g. "api-poll" or "api-register") If "event" is not provided, it will default to "iw" which was the former default.
 +
}}
 +
 
 +
{{RESTfulExample
 +
|title=Successfully Awarding a Token
 +
|summary=This demonstrates successfully awarding a token to a user.
 +
|request=profile: http://{client}.api.promo.eprize.com/v1/{apikey}/profile/{uid}.{webkey}
 +
|responsecode=201 Created
 +
|responseloc=/v1/{apikey}/game/{game}/token/{token}
 +
|response=<?xml version="1.0" encoding="UTF-8" ?>
 +
<result ver="1.0">
 +
<token>
 +
<id>{token}</id>
 +
<profile>{profile}</profile>
 +
<game>{game}</game>
 +
<redeemed>false</redeemed>
 +
</token>
 +
</result>
 +
|extranotes=The {profile} value that is seen in the request and response of this call is the canonical URL of the profile that the token should be awarded to.
This URL can be easily attacked by the owner of a profile because the owner knows his own canonical profile URL. Award limits create an upper bound on the attack damage.
This URL can be easily attacked by the owner of a profile because the owner knows his own canonical profile URL. Award limits create an upper bound on the attack damage.
 +
}}
 +
 +
{{RESTfulExample
 +
|title=Awarding Token to Invalid Profile
 +
|summary=This demonstrates attempting to award a token to a profile resource that doesn't exist.
 +
|request=profile: foo
 +
|responsecode=400 Bad Request
 +
|response=<?xml version="1.0" encoding="UTF-8"?>
 +
<result ver="1.0">
 +
<reason>Unable to validate the provided profile.</reason>
 +
<status>0</status>
 +
</result>
 +
}}
 +
 +
{{RESTfulExample
 +
|title=Awarding Token to a Limited Profile
 +
|summary=This demonstrates attempting to overaward tokens to a user. For example, the promotion is setup to give out 3 tokens per day per user, and this would be a users 4th attempt in one day.
 +
|responsecode=403 Forbidden
 +
|response=<?xml version="1.0" encoding="UTF-8"?>
 +
<result ver="1.0">
 +
</result>
 +
}}

Current revision

API Home Page :: Games and Awards

Summary

Award the profile a token, which is used to play the instant win game. The instant win game cannot be played without a valid token. Once a token has been redeemed, it cannot be used again.

A token ID returned after a successful token award which will be submitted as a resource argument when redeeming the token for an instant win play.

Multiple tokens could be accumulated before any are redeemed. Additionally, a profile's tokens can be checked for validity by using the fetch token resource.

Resource

/v1/{apikey}/game/{gameid}/tokens

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)

Parameters Required

profile: Canonical Location of a user profile. See: Fetch Profile by Key.

event: Name of an event to create an IW token for (must begin with "api-", e.g. "api-poll" or "api-register") If "event" is not provided, it will default to "iw" which was the former default.



Example: Successfully Awarding a Token

Summary

This demonstrates successfully awarding a token to a user.

Request 

profile: http://{client}.api.promo.eprize.com/v1/{apikey}/profile/{uid}.{webkey}

Response

HTTP Status Code: 201 Created

HTTP Redirect Location: /v1/{apikey}/game/{game}/token/{token} 

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

Notes

The {profile} value that is seen in the request and response of this call is the canonical URL of the profile that the token should be awarded to.

This URL can be easily attacked by the owner of a profile because the owner knows his own canonical profile URL. Award limits create an upper bound on the attack damage.

Example: Awarding Token to Invalid Profile

Summary

This demonstrates attempting to award a token to a profile resource that doesn't exist.

Request 

profile: foo

Response

HTTP Status Code: 400 Bad Request 


<?xml version="1.0" encoding="UTF-8"?>
<result ver="1.0">
  <reason>Unable to validate the provided profile.</reason>
  <status>0</status>
</result>


Example: Awarding Token to a Limited Profile

Summary

This demonstrates attempting to overaward tokens to a user. For example, the promotion is setup to give out 3 tokens per day per user, and this would be a users 4th attempt in one day.


Response

HTTP Status Code: 403 Forbidden 


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


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