Create profile

From ePrize Developers Wiki

(Difference between revisions)
Jump to: navigation, search
Current revision (15:57, 6 April 2011) (edit) (undo)
 
(22 intermediate revisions not shown.)
Line 1: Line 1:
-
<pre>
+
{{RESTfulAPI
-
Request representation:
+
|crumbs=[[API Home Page]] :: [[Profiles]]
-
{profile-key}:{profile-value}
+
|summary=Create a [[Profiles|profile]] in the [[API Key]] with profile fields. This profile can be awarded and Instant Win play or a Sweepstakes entry and can be retrieved later.
-
{key1}:{value1},
+
 
-
{key2}:{value2},
+
Promotions are always configured with one unique {profile-key} such as email, user_name, or mobile_phone. When creating a profile, the profile must have a {profile-value} for this key and {profile-value} must be unique within the promotion.
 +
 
 +
If profile creation is successful, a unique URL identifying the profile will be returned in the HTTP "Location" header. If tunneling is requested, the URL will be present in the body of the response in the "location" attribute on the top-level element. HTTP responses may pass through additional proxy layers which alter the case of the "Location" header--the HTTP standard requires header names to be case-insensitive.
 +
 
 +
Additional key:value pairs may be submitted. The {apikey} may enforce rules on these pairs such as required vs optional, size limits and validation. Common examples of other keys are address, birthdate and optin. The name of a key must begin with a letter and consist of only lowercase ASCII letters, numbers and underscores. The specific behavior depends entirely on a promotion's configuration.
 +
 
 +
Typically the {apikey} will be configured to require a CAPTCHA challenge/response in the request headers of an untrusted create profile request. A failed CAPTCHA is the same as a failed validation, resulting in a response of 400 Bad Request.
 +
 
 +
This URL is an entry point. It may be easily attacked because valid URLs are easy to guess. CAPTCHA protects against automated attacks.
 +
|resource=/v1/{apikey}/profiles
 +
|methods=POST
 +
|resourceargs='''apikey''': Your [[API Key]]
 +
|paramsrequired=Profile field name and value pairs. Specific profile field names will be predefined for your [[API Key]] and will be provided with the [[API Key]].
 +
}}
 +
 
 +
{{RESTfulExample
 +
|title=Profile Created
 +
|summary=This demonstrates a successful profile creation. The form parameters should be sent as application/x-www-form-urlencoded
 +
|request=Form Post Variables
 +
email=some.email@address.com&
 +
public1=public-value1&
 +
public2=public-value2&
 +
...
 +
publicN=public-valueN&
 +
private1=private-value1&
 +
private2=private-value2&
...
...
-
{keyN}:{valueN}
+
privateN=private-valueN
-
</pre>
+
-
Profile Created
+
 
-
<pre>
+
|responsecode=201 Created
-
HTTP Status: 201 Created
+
|responseloc=/v1/{apikey}/profile/{uid}.{webkey}
-
Location: /v1/{apikey}/profile/{uid}
+
|response=<?xml version="1.0" encoding="UTF-8" ?>
-
<?xml version="1.0" encoding="UTF-8" ?>
+
<result ver="1.0">
-
<result ver="ePrize Web Services 1.0">
+
<profile>
-
<result>
+
<id>{profile-number}</id>
-
<profile>
+
<email>some.email@address.com</email>
-
<id>{uid}</id>
+
<public1>public-value1</public1>
-
<email>some.email@address.com</email>
+
<public2>public-value2</public2>
-
<safekey1>safekey1-value</safekey1>
+
...
-
<safekey2>safekey2-value</safekey2>
+
<publicN>public-valueN</publicN>
-
</profile>
+
</profile>
-
</result>
+
-
<status>1</status>
+
</result>
</result>
-
</pre>
+
}}
-
Profile Already Exists
+
{{RESTfulExample
-
<pre>
+
|title=Profile Already Exists
-
HTTP Status: 409 Conflict
+
|summary=This demonstrates an attempted profile creation that got rejected because a profile with the unique id (email in most cases) already exists.
-
<?xml version="1.0" encoding="UTF-8" ?>
+
|responsecode=409 Conflict
-
<result ver="ePrize Web Services 1.0">
+
|response=<?xml version="1.0" encoding="UTF-8" ?>
-
<result>
+
<result ver="1.0">
-
<errors>
+
<terminal_error>duplicate_account</terminal_error>
-
<terminal_errors>
+
-
<error>duplicate_account</error>
+
-
</terminal_errors>
+
-
</errors>
+
-
</result>
+
-
<status>1</status>
+
</result>
</result>
-
</pre>
+
}}
-
Invalid Request - Errors
+
{{RESTfulExample
-
<pre>
+
|title=Invalid Request - Errors
-
HTTP Status: 400 Bad Request
+
|responsecode=400 Bad Request
-
<?xml version="1.0" encoding="UTF-8" ?>
+
|response=<?xml version="1.0" encoding="UTF-8" ?>
-
<result ver="ePrize Web Services 1.0">
+
<result ver="1.0">
-
<result>
+
<input_error>
-
<errors>
+
<error>VALIDATION</error>
-
<field_errors>
+
<name>field1</name>
-
<field>
+
</input_error>
-
<name>field1</name>
+
<input_error>
-
<error>VALIDATION</error>
+
<name>field2</name>
-
</field>
+
<error>NULL</error>
-
<field>
+
</input_error>
-
<name>field2</name>
+
...
-
<error>NULL</error>
+
<input_error>
-
</field>
+
<name>fieldN</name>
-
...
+
<error>NULL</error>
-
<field>
+
</input_error>
-
<name>fieldN</name>
+
-
<error>NULL</error>
+
-
</field>
+
-
</field_errors>
+
-
</errors>
+
-
</result>
+
-
<status>1</status>
+
</result>
</result>
-
</pre>
+
}}
-
Promotion is configured with one unique {profile-key} such as email, user_name, or mobile_phone. At a minimum, the profile must have a {profile-value} for this key and {profile-value} must be unique within the promotion.
+
{{RESTfulExample
-
 
+
|title=Invalid Request - Errors in JSON Format
-
Additional key:value pairs may be submitted. The {apikey} may enforce rules on these pairs such as required vs optional, size limits and validation. Common examples of other keys are address, birthdate and optin. The name of a key must begin with a letter and consist of only lowercase ASCII letters, numbers and underscores.
+
|responsecode=400 Bad Request
-
 
+
|response={
-
Typically the {apikey} will be configured to require a CAPTCHA challenge/response in the request headers of an untrusted create profile request. A failed CAPTCHA is the same as a failed validation, resulting in a response of 400 Bad Request.
+
"result" : {
-
 
+
"input_error" : [
-
This URL is an entry point. It may be easily attacked because valid URLs are easy to guess. CAPTCHA protects against automated attacks.
+
{
 +
"error" : "NULL",
 +
"name" : "field1"
 +
},
 +
{
 +
"name" : "field2"
 +
"error" : "VALIDATION",
 +
},
 +
...
 +
{
 +
"error" : "NULL",
 +
"name" : "fieldN"
 +
},
 +
]
 +
}
 +
}
 +
}}

Current revision

API Home Page :: Profiles

Summary

Create a profile in the API Key with profile fields. This profile can be awarded and Instant Win play or a Sweepstakes entry and can be retrieved later.

Promotions are always configured with one unique {profile-key} such as email, user_name, or mobile_phone. When creating a profile, the profile must have a {profile-value} for this key and {profile-value} must be unique within the promotion.

If profile creation is successful, a unique URL identifying the profile will be returned in the HTTP "Location" header. If tunneling is requested, the URL will be present in the body of the response in the "location" attribute on the top-level element. HTTP responses may pass through additional proxy layers which alter the case of the "Location" header--the HTTP standard requires header names to be case-insensitive.

Additional key:value pairs may be submitted. The {apikey} may enforce rules on these pairs such as required vs optional, size limits and validation. Common examples of other keys are address, birthdate and optin. The name of a key must begin with a letter and consist of only lowercase ASCII letters, numbers and underscores. The specific behavior depends entirely on a promotion's configuration.

Typically the {apikey} will be configured to require a CAPTCHA challenge/response in the request headers of an untrusted create profile request. A failed CAPTCHA is the same as a failed validation, resulting in a response of 400 Bad Request.

This URL is an entry point. It may be easily attacked because valid URLs are easy to guess. CAPTCHA protects against automated attacks.

Resource

/v1/{apikey}/profiles

Valid Methods

POST

Resource Arguments

Note: resource arguments are always required.

apikey: Your API Key

Parameters Required

Profile field name and value pairs. Specific profile field names will be predefined for your API Key and will be provided with the API Key.



Example: Profile Created

Summary

This demonstrates a successful profile creation. The form parameters should be sent as application/x-www-form-urlencoded

Request 

Form Post Variables
email=some.email@address.com&
public1=public-value1&
public2=public-value2&
...
publicN=public-valueN&
private1=private-value1&
private2=private-value2&
...
privateN=private-valueN

Response

HTTP Status Code: 201 Created

HTTP Redirect Location: /v1/{apikey}/profile/{uid}.{webkey} 

<?xml version="1.0" encoding="UTF-8" ?>
<result ver="1.0">
  <profile>
    <id>{profile-number}</id>
    <email>some.email@address.com</email>
    <public1>public-value1</public1>
    <public2>public-value2</public2>
    ...
    <publicN>public-valueN</publicN>
  </profile>
</result>


Example: Profile Already Exists

Summary

This demonstrates an attempted profile creation that got rejected because a profile with the unique id (email in most cases) already exists.


Response

HTTP Status Code: 409 Conflict 


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


Example: Invalid Request - Errors

Response

HTTP Status Code: 400 Bad Request 


<?xml version="1.0" encoding="UTF-8" ?>
<result ver="1.0">
  <input_error>
    <error>VALIDATION</error>
    <name>field1</name>
  </input_error>
  <input_error>
    <name>field2</name>
    <error>NULL</error>
  </input_error>
  ...
  <input_error>
    <name>fieldN</name>
    <error>NULL</error>
  </input_error>
</result>


Example: Invalid Request - Errors in JSON Format

Response

HTTP Status Code: 400 Bad Request 


{
  "result" : {
    "input_error" : [
      {
        "error" : "NULL",
        "name" : "field1"
      },
      {
        "name" : "field2"
        "error" : "VALIDATION",
      },
      ...
      {
        "error" : "NULL",
        "name" : "fieldN"
      },
    ]
  }
}


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