Validate and consume code

From ePrize Developers Wiki

Revision as of 14:12, 31 March 2014

API Home Page :: Code Services

Summary

Code Services allows promotion builders to take advantage of Helloworld's robust Code Services platform. When submitting a new promotion request, you may specify certain code configurations that will take effect in your promotion. These codes may be used for many different scenarios -- a code may be required on registration, for example, or a user may be awarded a game play if they give a valid code. The code configurations are quite extensible, please contact us if you have any questions.

This resource will not respond correctly if your API Key is not configured for codes.

Resource

/v1/{apikey}/codes/{codeClass}/{code}

Valid Methods

POST

Resource Arguments

Note: resource arguments are always required.

apikey: Your API Key.

codeClass: there may be multiple code classes in an API Key

code: the code provided by the user.

Parameters Required

None.

Note: some user agents have trouble with blank POST request. Please try adding a name/value pair into the request representation if you you are having trouble (i.e. foo=bar)

Example: Successfully Validate & Consume a Code

Summary

This demonstrates successfully validating and consuming a code.

Request

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

Response

HTTP Status Code: 200 OK

<?xml version="1.0" encoding="UTF-8" ?>
<result ver="1.0">
  <codeResponse>
    <code>{code}</code>
    <codeClass>{codeClass}</codeClass>
  </codeResponse>
</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.

Example: Attempting to Validate & Consume a Code with no Profile

Summary

This demonstrates an unsuccessful attempt at validating & consuming a code without providing a profile (or providing a bad one).

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>
</result>

Example: Attempting to Validate & Consume a Code that doesn't exist

Summary

This demonstrates an unsuccessful attempt at validating & consuming a code that doesn't exist, or a code for a code class that doesn't exist. These scenarios both return the same error to avoid giving too much information to possibly malicious users.

Response

HTTP Status Code: 404 Not Found

<?xml version="1.0" encoding="UTF-8"?>
<result ver="1.0">
  <reason>The specified code does not exist.</reason>
</result>

Example: Attempting to Validate & Consume a Code that has already been used

Summary

This demonstrates an unsuccessful attempt at validating & consuming a unique code that has already been used.

Response

HTTP Status Code: 403 Permission Denied

<?xml version="1.0" encoding="UTF-8"?>
<result ver="1.0">
  <reason>The specified code has already been used.</reason>
</result>

Example: Attempting to Validate & Consume a Code whose limit has been reached

Summary

This demonstrates an unsuccessful attempt at validating & consuming a code belonging to a class for which the limit has already been reached(e.g. "the user may enter up to 3 codes per day").

Response

HTTP Status Code: 403 Permission Denied

<?xml version="1.0" encoding="UTF-8"?>
<result ver="1.0">
  <reason>The limit has been reached.</reason>
</result>