Validate and consume code

From ePrize Developers Wiki

Revision as of 15:38, 20 April 2011

API Home Page :: Code Services

Summary

Code Services allows promotion builders to take advantage of ePrize'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.

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>