A Product relates to a specific crowdsourcing service offered by Clickworker, such as text creation, translation, etc. There are two types of products:
- Standard products: These are off-the-shelf, preconfigured products for direct use as offered via the Marketplace
- Solutions products: These are custom services tailored for specific customer projects.
Using the Marketplace API, customers can order and use preconfigured Marketplace products or submit new tasks for custom products. In order to use a standard product, the customer must select the product using the appropriate resource URI and provide the additional parameters required for the chosen product, such as the target language for text creation.
Attributes
| Name | Type | Access | Description |
|---|---|---|---|
| available | Boolean | r/- | true, if the product is currently available for ordering |
| attributes | List | r/- | A list of product attributes that are supported (and sometimes required) to configure the product. See the “Product Attribute” section for a formal description. |
Representation
The Product entity supports indexed and detailed views (see section API Princpiples - Representing Resources Using XML or JSON).
XML Representation
#Detail View
<product>
<link href=”[context]/products/${code}” rel=”self” type=”application/xml” />
<code>${code}</code>
<title>${title}</title>
<description>${description}</description>
<available>${available}</available>
<attributes>
<code>${code}</code>
<type>${type}</type>
<is_mandatory>${mandatory}</is_mandatory>
<titles>
<$<en|de|fr>>${title}</$<en|de|fr>
</titles>
<helps>
<$<en|de|fr>>${help}</$<en|de|fr>
</helps>
<options>
<titles>
<$<en|de|fr>>${title}</$<en|de|fr>
</titles>
<value>${opt_value}</value>
</options>
</attributes>
</product>
#Index View
<product>
<link href=”[context]/products/${code}” rel=”self” type=”application/xml” />
<code>${code}</code>
<titles>
<$<en|de|fr>>${title}</$<en|de|fr>
</titles>
<available>${available}</available>
</product>
JSON Representation
#Detail View
product: {
link: [{
href: “[context]/products/${code}”,
rel: “self”,
type: “application/json”
}],
code: “${code}”,
titles: {
“$<en|de|fr>”: “${title}”
},
descriptions: {
“$<en|de|fr>”: “${description}”
},
available: ${available},
attributes: [{
“code”: “${code}”,
“type”: “${type}”,
“is_mandatory”: ${is_mandatory},
titles: {
“$<en|de|fr>”: “${title}”
},
help: “${title}”,
options: [{
titles: {
“$<en|de|fr>”: “${title}”
},
value”: “${opt_value}“
}]
}]
}
#Index View
{
link: [{
href: “[context]/products/${code}”,
rel: “self”,
type: “application/json”
}],
code: “${code}”,
titles: {
“$<en|de|fr>”: “${title}”
},
available: ${available}
}
Operations
List Available Products
Displays a brief summary of each product. Note: This operation only lists products that are currently available. Deprecated products may still be accessed using their URI for reference in existing orders.
Request
Request line:
GET [context]/products/
Request parameter:
(Common only)
Request body:
(Empty)
Response
Response status:
- 200, if the request could be properly handled (even if no products were found)
Response Body:
<products_response>
<request_status>...</request_status>
<products>
<link href=“/api/marketplace/v2/products/TextCreate”
rel=”product”
type=”application/xml” />
<code>TextCreate</code>
<titles>
<en>Text creation</en>
</titles>
<available>true</available>
</products>
<products>
<link href=“/api/marketplace/v2/products/TextCreateWithKeywords”
rel=”product”
type=”application/xml” />
<code>TextCreateWithKeywords</code>
<titles>
<en>Text creation with keywords</en>
</titles>
<available>true</available>
</products>
</products_response>
JSON Example
{
request_status: ... ,
products: [{
link: [{
href: “/api/marketplace/v2/products/TextCreate”,
rel: “product”,
type: “application/json”
}],
code: “TextCreate”,
titles: {
en: “Text creation”
},
available: true
},{
link: [{
href: â pi/marketplace/v2/products/TextCreateWithKeywords”,
rel: “product”,
type: “application/json”
}],
code: “TextCreateWithKeywords”,
titles: {
en: “Text creation with keywords”
},
available: true
}]
}
View Product Details
Request
Request line:
GET [context]/products/${code}
Request parameter:
(Common only)
Request body:
(Empty)
Response
Response status:
-
200, if the addressed resource was found
-
404, if the addressed resource was not found
Response body:
- XML Example
<product_response>
<request_status>...</request_status>
<product>
<link href=“/api/marketplace/v2/products/product_research”
rel=”self”
type=”application/xml” />
<code>product_research</code>
<titles>
<en>Product Research</en>
</titles>
<descriptions>
<en>Identify product details using a Internet search.</en>
</descriptions>
<available>true</available>
<attributes>
<code>research_language</code>
<type>option</type>
<is_mandatory>true</is_mandatory>
<titles>
<en>Research Language</en>
</titles>
<helps>
<en>
Defines the language to use for creating the research result.
</en>
</helps>
<options>
<titles>
<en>German</en>
</titles>
<value>de</value>
</options>
<options>
<titles>
<en>English</en>
</titles>
<value>en</value>
</options>
</attributes>
</product>
</product_response>
- JSON Example
product_response: {
request_status: ... ,
product: {
link: [{
href: “/api/marketplace/v2/products/product_research”,
rel: “self”,
type: “application/json”
}],
code: “product_research”,
titles: {
en: “Product Research”
},
descriptions: {
en: “Identify product details using a Internet search.”
},
available: true,
attributes: [{
code: “research_language”,
type: “option”,
is_mandatory: true,
titles: {
en: “Research Language”
},
helps: {
en: “Defines the language to use for creating the research result.”
},
options: [{
titles: {
en: “German”
},
value: “de”
},{
titles: {
en: “English”
},
value: “en”
}]
}]
}
}
Product Attribute
Product Attributes provide meta information about parameters required for task submission. Each product may require one or more additional parameters to be supplied when submitting a task, such as the requested target language for text creation. Task Templates are used to store sets of Product Attribute values along with other information such as the work instructions.
Although every Product may have a dedicated set of required and optional Product Attributes, the Product Attribute itself is a standardized element.
Attributes
| Name | Type | Access | Description |
|---|---|---|---|
| code | String | r/- | A symbolic name for the Product Attribute URI compatible |
| type | String | r/- | Product Attribute type indicator. One of the following:string: for text attributes, option: for predefined attribute values, integer: for numeric attributes, date: for time-based attributes |
| titles | Localized String | r/- | The localized title of this Product Attribute |
| helps | Localized Text | r/- | The localized help text for this Product Attribute |
| is_mandatory | Boolean | r/- | Mandatory indicator |
| min_length | numeric | r/- | Minimum text value length for type=string |
| max_length | numeric | r/- | Maximum text value length for type=string |
| options | List | r/- | A list of predefined attribute values, only present if type is “option.” An option has two attributes: 1. The options value (opt_value) 2. The options title (opt_title), localized |
| value | String | r/w | The Product Attribute’s value |
Representation
XML Representation
<attribute>
<code>${code}</code>
<type>${type}</type>
<is_mandatory>${mandatory}</is_mandatory>
<titles>
<$<en|de|fr>>${title}</$<en|de|fr>>
</titles>
<helps>
<$<en|de|fr>>${help}</$<en|de|fr>>
</helps>
<options>
<titles>
<$<en|de|fr>>${opt_title}</$<en|de|fr>>
</titles>
<value>${opt_value}</value>
</options>
</attribute>
JSON Representation
{
“code”: “${code}”,
“type”: “${type}”,
“is_mandatory”: ${is_mandatory},
titles: {
“$<en|de|fr>”: “${title}”
},
helps: {
“$<en|de|fr>”: “${title}”
},
options: [{
titles: {
“$<en|de|fr>”: “${title}”
},
value”: “${opt_value}“
}]
}