Marketplace API References

Clickworker Marketplace API

Clickworker’s REST-based Web services allow customers to access the company’s crowdsourcing services through an API and integrate them seamlessly into their applications. The API has been designed to meet the needs of two distinct customer groups:

• Customers buying predefined products from the Clickworker Marketplace
• Customers uploading data for projects managed by the Clickworker solutions team.

Customers may use the API to order services offered in the Clickworker Marketplace. Clickworker offers a wide range of services, such as content creation, text translation and Internet research. Customers may use these services through the Web based marketplace portal on http://www.clickworker.com or by integrating them through the Clickworker Marketplace API. Most of our marketplace products can be customized to meet the specific data format requirements of customers, such as the number of fields to research. All products are based on Clickworker’s leading edge quality control and quality assurance technology.

Customers who order custom projects managed by the Clickworker solutions department may use the API to integrate their IT systems with the Clickworker crowdsourcing platform in order to submit new tasks and review results on an ongoing basis.

Who Should Read This Guide

This document’s primary audience is our clients’ software developers. It aims to provide a brief description of each API entity and its available operations. Practical examples will be included to assist with implementation.

Required Knowledge and Skills

Familiarity with the following is recommended before using this guide:

• Basic understanding of the Extensible Markup Language (XML) or JavaScript Object Notation (JSON)
• Basic understanding of the Hypertext Transfer Protocol (HTTP)

Typing

The following conventions will be used throughout this guide:

• Arguments, in either the form of request parameters or response variables, are put inside curly braces and prefixed by a dollar sign ($). They use a unique name that corresponds to the associated explanation (Example: “${id}”).
• References to API entities use square brackets, prefixed by a dollar sign (Example: $[Request Status]). If the reference points to a list containing any amount of instances of the referenced entity (or none at all, for that matter), an asterisk (*) is appended to the entity’s name.
• Values for variables and parameters are put inside chevrons and prefixed by a dollar sign. If the value can be chosen from a predefined list of values, the pipe character is used. Examples: “$<GET|POST>”.
• Patterns that need to be replaced by a meaningful substitute are put inside square brackets, like [context].

Key Concepts

Business Objects

Clickworker offers a wide range of services that enable data that is unsuitable for automatic processing to be handled by human workers. We call this “crowdsourcing.” The data provided by the customer is converted into what we call “tasks” (see section Task). Using a customizable workflow, jobs (see section Job) are created for every task, representing the workflow’s steps. Examples of jobs include “create text” and “review text.” Clickworker then offers these jobs to registered users worldwide. These users are called “clickworkers”.

Once all jobs are finished, the task is completed. The resulting data is then returned to the customer, who will be given the opportunity to verify and sign off on the result. (Depending on the product and the customer’s requirements.)

Server/Client Communication

The Clickworker Marketplace API provides access to business objects (resources) in a “RESTful” manner:

• Resources are identified using a Uniform Resource Identifier (URI). They can be represented in various formats, like XML or JSON.
• HTTP “verbs” (e.g. GET or POST) are used to call available operations on these resources. The outcome of an operation is reported using HTTP status codes (e.g. “200 OK”). Additional information may be available in the response’s body.
• Clients must authenticate themselves using HTTP authentication (“Basic Auth”). To ensure confidentiality, Transport Layer Security (TLS/SSL) is used.

A more in-depth description of the API principles is available in section API Concepts.

Runtime Environments

To support testing of new clients and gather feedback for new API versions as early as possible, various environments host installations of the Marketplace API:

• Production: This is the production environment. It uses the latest released version of the Marketplace API, works with production data, and fully interacts with external systems, like email servers or partner gateways.

The current production environment is available at https://api-production.clickworker.com/api/marketplace/v2/

• Sandbox: This is the testing environment. It uses the latest released version of the Marketplace API, works with dedicated test data, and has limited interaction with external systems, like email servers or partner gateways. Customers can use this environment to test their clinet implementations.

The current sandbox environment is available at https://api-sandbox.clickworker.com/api/marketplace/v2/

• Sandbox beta: This is the staging environment. It uses the upcoming version of the Marketplace API. Because this is a beta environment, it may contain bugs. The sandbox beta environment works with dedicated test data and has limited interaction with external systems. Customers can use this environment to update their clients to the next version of the API.

The current sandbox beta environment is available at https://api-sandboxbeta.clickworker.com/api/marketplace/v2/

Localization Support

The Marketplace API supports localization. Clients can send information about the preferred locale using standard HTTP headers (Accept-Language). The server will provide information about the content language using the Content-Language HTTP header.

Entities that support multiple languages during creation (as TaskTemplate does) make use of embedded XML elements or JSON value pairs, using the language code as the key.

There will always be an English version available; all other languages are optional. For simplicity, English is the only language that will be used in examples demonstrating API entities.

Example:

# XML Representation
  <titles>
    <de>Dies ist eine deutsche Nachricht</de>
    <en>This is an English message</en>
  </titles>

# JSON Representation
  titles: {
    de: “Die ist die deutsche Nachricht”,
    en: “This is the English message”
  }

API Concepts

This chapter describes the API’s key concepts. All available entities are listed in the following sections, along with the available operations to manipulate them.

Almost every entity supports at least some of the typical CRUD operations (Create, Read, Update, Delete). For every operation, the following details are given:

1. Request format and content, built from: a. The request line, according to the HTTP 1.1 protocol b. The request body description (if any)
2. Response format and content, built from: a. The main HTTP status codes (see section “Reporting status using HTTP codes” for all status codes) b. The response body content (if any)
3. Arguments that are used in the request (parameter) or the response (variables)

Context

All HTTP request lines used in this section make use of a special [context] marker. The context is the base part of every operation’s URI. It is built from the host’s name, the API version, and the API base path.

The [context] marker must be replaced by the following content: https://api.clickworker.com/api/marketplace/v2/

Common Aspects

In general, a request that creates or modifies (updates) an entity must contain a valid representation of that entity (in XML or JSON format) in the request body. It must contain the writable attributes of the entity.

When one or more entities are part of a response body, they will be enclosed in a container element (XML element or anonymous JSON object), prefixed by a request status.

Attributes

Entities support a variety of attributes. The specific attributes are listed inside a table for each entity. Attributes that can be set using the API at creation time are marked as “r/c“. Those that can be set at any time are marked as “r/w”. All others are read-only (“r/-“).

Attribute names are re-used wherever they serve the same purpose. The following table lists the most common attributes:

Common Request Parameters

There is a set of URL parameters that control common aspects of all API operations or result representations.

The following table lists and explains them:

Name Value(s) Synopsis

Common Response Parameters

Every response contains a set of common parameters. Depending on whether a single resource (entity) or a collection was requested, either a single entity or a list of entities is returned. Every response will contain the request status, indicating whether the request was successful or resulted in an error.

If a single entity was created, updated, or requested for reading, this entity will be part of the response, in addition to the request status. For technical reasons, a wrapper element (XML element or JSON object) will be used for response bodies.

The naming conventions for the global container elements are

• [entity type] + “response” for single instance responses, e.g. “customer_response”
• [entity type] + “s_response reference nstance responses, e.g. “customers_response”

If the response contains multiple instances, no additional container elements will be used. Instead, every element’s name will follow the convention [entity_type] + “s”. For JSON, the actual entities in the collection will be anonymous JSON objects.

Examples

- XML Representation (Single Entity Response)
  <task_response>
    <request_status>...</request_status>
    <task> ... </task>
  </task_response>

- XML Representation (Multiple Entities Response)
  <tasks_response>
    <request_status>...</request_status>
    <tasks>...</tasks>
    <tasks>...</tasks>
  </tasks_response>

- JSON Representation (Single Entity Response)
  task_response: {
    request_status: { ... },
    task: { ... }
   }

- JSON Representation (Multiple Entities Response)
  tasks_response: {
    request_status: { ... },
    tasks: [{
    ]}
  }

Request Status

The Request Status provides the success or error information of the request. In general, it repeats the HTTP status code and contains additional, human-readable error messages. It also contains information about the pagination of the results.

Attributes

• XML Representation

  <request_status>
    <id>${id}</id>
    <valid>${valid}</valid>
    <status_code>${status_code}</status_code>
    <status_text>${status_text}</status_text>
    <messages>${message}</messages>
    <total_count>${total_count}</total_count>
    <page_num>${page_num}</page_num>
    <page_size>${page_size}</page_size>
  </request_status>

• JSON Representation

  request_status: {
    id: “${id}”,
    valid: ${valid},
    status_code: ${status_code},
    status_text: ${status_text},
    messages: [
      “${message}”
    ],
    total_count: ${total_count},
    page_size: ${page_size},
    page_num: ${page_num}
  }

Examples

• XML Representation

  <request_status>
    <id>az3n12j3h5b453j</id>
    <valid>false</valid>
    <status_code> 409 </status_code>
    <status_text>Conflict</status_text>
    <messages>The Task Template cannot be deleted. It is used by
the following Tasks: 1313, 1213, 1234!</messages>
    <total_count>0</total_count>
    <page_size>0</page_size>
    <page_num>1</page_num>
  </request_status>

• JSON Representation

  request_status: {
    id: “az3n12j3h5b453j”,
    valid: true,
    status_code: 204 ,
    status_text: No Content,
    messages: [
      “Resource has been deleted.”
    ],
    total_count: 0,
    page_size: 0,
    page_num: 1
  }

API Usage

The following chapter lists all available entities and their operations. It is structured to match the typical development process, beginning with customer account handling and moving on to selection and configuration of products, creation of task templates and tasks, and progress observation using jobs and notifications.

Before performing specific API operations, developers should verify the general communication setup by using the two dedicated “echo” services, described in section API Principles - Authentication and transport security.

For every entity, a short description, an attribute list (which excludes the common attributes in section Common Response Parameters) and a description of the available operations are given.