Reference of all API calls available. Consult also the concepts documentation and the Swagger documentation available for the interactive version of the API.

Whenever the customer confirms a new task, it is accomplished based on a predefined, product-specific workflow. The steps of this workflow are called “Jobs.” This is illustrated by the following workflow, consisting of three Jobs:

  1. “create” performed by a clickworker writing a text according to a task’s specifications

  2. “review” performed by another clickworker who reviews the results of the first job

  3. “signoff” performed by the customer, who approves or declines the results.

A task is completed when the entire workflow is completed. This occurs when all jobs are finished.

Using the Marketplace API, customers can only see and manipulate jobs that are assigned to them. Usually, these are jobs for signing off on the results. The product details contain the relevant meta information about the job’s input and results.

Attributes

Name Type Access Description
href URI r/- The Job resource identifier
id String r/- The Job Id
task Task r/- The Task with which this Job is associated
customer_ref String r/- Copied from the associated Task
items List r/- The Job’s payload, a combination of the task input data provided by the customer and the clickworker output
form List r/- A list of Form Elements that visualize the required and supported input items (see below)
input List r/w A list of items supplied for job completion. The purpose, format, and the available alternatives (if any) are described by the form attribute above.

Representation

  • XML Representation (Detail View)
<job>
  <link href=”[context]/customer/jobs/${id}” rel=”self” type=”application/json” />
  <id>${id}</id>
  <task>
    <link href=”[context]/customer/tasks/${task}” rel=”task” type=”application/xml” />
  </task>
  <items>
    <code>${item_code}</code>
    <content>${item_content}</content> 
  </items>
  <form>
    <elements>
      <type>$<text_field|text_area|number|keyword|email|url|select></type>
      <titles> 
        <$<en|fr|de>>${title}</$<en|fr|de>>
      </titles> 
      <descriptions>
        <$<en|fr|de>>${description}</$<en|fr|de>> 
      </descriptions> 
      <item_code>${item_code}</item_code> 
      <is_output>${is_output}</is_output>
      <is_mandatory>${is_mandatory}</is_mandatory>
      <options>
        <code>${opt_code}”></code>
        <value><![CDATA[${opt_value}]]></value> 
      </options>
    </elements>
  </form> 
  <input>
    <items>
      <code>${item_code}</code> 
      <content>${item_content}</content>
    </items> 
  </input>
</job>
  • XML Representation (Index View)
<job>
  <link href=”[context]/customer/jobs/${id}” rel=”self”
type=”application/xml” /> 
  <task>
    <link href=”[context]/customer/tasks/${task}” rel=”task” type=”application/xml”/>
  </task>
</job>
  • JSON Representation (Detail View)
job: {
  link: [{
    href: “[context]/customer/jobs/${id}”, rel: “self”,
    type: “application/json”
  }],
  id: ${id}, task: {
    link: [{
      href: “[context]/customer/tasks/${task}”, rel: “task”,
      type: “application/json”
    }] },
    items: [{
      code: “${item_code}”,
      content: “${item_content}” 
    }],
    form: [{
      type: “$<text_field|text_area|number|keyword|  email|url|select>”,
      titles: {
        “$<en|fr|de>”: “${title}”
      }, 
      descriptions: {
        “$<en|fr|de>”: “${description}” 
      },
      item_code: “${item_code}”, is_output: $  {is_output}, is_mandatory: ${is_mandatory}, options:   [{
        code: “${opt_code}”,
        value: ${opt_value} }]
      }], 
      input: {
        items: [{
          code: “${item_code}”, content: “${item_content}”
        }] 
    }
}
  • JSON Representation (Index View)
job: {
  link: [{
    href: “[context]/customer/jobs/${id}”, rel: “self”,
    type: “application/json”
  }], 
  task: {
    link: [{
      href: “[context]/customer/tasks/${task}”, rel: “task”,
      type: “application/json” 
    }] 
  }
}

Operations

Index Registered Jobs

There are two ways to index Jobs associated with a customer’s account:

  1. View all Job instances that are assigned to a customer
  2. Only view Jobs that are associated with a specific Task

Request

**Request Line **

GET [context]/customer/jobs/

or

GET [context]/customer/tasks/${id}/jobs/

Request parameter:

Name Type Synopsis Mandatory
id Integer The auto-generated Job id. Yes

Request Body: (empty)

Response

Response Status:

  • 200, if the index was built (even if it does not contain any Jobs)
  • 404, if the addressed Task does not exist

Response body:

  • XML Example
<jobs_response> 
  <request_status>...</request_status> 
  <jobs>
    <link href=“/api/marketplace/v2/customer/jobs/1234” rel=”job” type=”application/xml” />
    <task>
      <link href=“/api/marketplace/v2/customer/tasks/5678”
rel=”task” type=”application/xml” /> 
    </task>
  </jobs> 
</jobs_response>
  • JSON Example
jobs_response: { 
  request_status: { ... } , 
  jobs: [{
    link: [{
      href: “/api/marketplace/v2/customer/jobs/1234”,    
      rel: “job”,
      type: “application/json”
    }], 
    task: [{
      href: “/api/marketplace/v2/customer/tasks/5678”, 
      rel: “task”,
      type: “application/json”
    }]
  }] 
}

View Job Details

Request

Request line:

GET [context]/customer/tasks/${task_id}/jobs/${id}

Request Parameter

Name Type Synopsis Mandatory
task_id integer The auto-generated Task id, as returned by the Create Task operation Yes
id integer The autogenerated Job id, as returned by the Create Notification operation Yes

Request body:

(empty)

Response

Response status

  • 200, if the Job was found
  • 404, if the Job or the Task was not found

Response body

  • XML Example
<job_response> 
  <request_status>...</request_status> 
  <job>
    <link href=“/api/marketplace/v2/customer/jobs/1234” rel=”self” type=”application/xml” />
    <id>1234</id> 
    <task>
      <link href=“/api/marketplace/v2/customer/tasks/5678” rel=”task” type=”application/xml” />
    </task>
    <items><code>source</code><content>English Term</content></items>
    <items><code>target</code><content>Deutscher Begriff</contents></items>
  </job> 
</job_response>
  • JSON Example
job_response: { 
  request_status: ... , 
  job: {
    link: [{
      href: “/api/marketplace/v2/customer/jobs/1234”,
      rel: “self”,
      type: “application/json”
    }],
    id: 1234,
    task: {
      link: [{
        href: “/api/marketplace/v2/customer/tasks/456” 
        rel: “task”
        type: “application/json”
       }] 
    },
    items: [{
      code: “source”, 
      content: “English Term”
    },{
      code: “target”,
      content: “deutscher Begriff”
    }] 
  }
}

Update Jobs

To update a Job, the input attribute’s content must match the structure of the embedded form.

Request

Request line:

PUT [context]/customer/jobs/${id}

or

POST [context]/customer/jobs/${id}?_method=PUT

Request parameter:

Name Type Synopsis Mandatory
task_id Integer The auto-generated Task id, as returned by the Create Task Operation Yes
id Integer The auto-generated Job id Yes

Request Body

  • XML Example
<job>
  <input> 
    <items> 
      <code>accepted</code> 
      <content>1</content>
    </items>
<!-- evaluation points for grammar: 4-no error, 3-less erorrs, 2-many errors, 0-not acceptable-->

    <items> 
      <code>grade_gr</code> 
      <content>2</content>
    </items>
<!-- comment for grammar --> 
    <items>
      <code>grade_gr_comment</code>
      <content>Here is my grade_gr comment</content>  
    </items>
<!-- evaluation points for spelling and punctuation: 4-no error, 3-less erorrs, 2-many errors, 0-not acceptable-->
    <items> 
      <code>grade_sppu</code> 
      <content>2</content>
    </items>
<!-- comment for für grade_sppu--> 
    <items>
      <code>grade_sppu_comment</code> 
      <content>Here is my spelling and punctuation comment </content>
    </items>
<!-- evaluation points for style: 4-no error, 3-less erorrs, 2-many errors, 0-not acceptable-->
    <items> 
      <code>grade_sest</code> 
      <content>2</content>
    </items>
<!-- comment for für style --> 
    <items>
      <code>grade_sest_comment</code>
      <content>Here is my style comment</content> 
    </items>
<!-- evaluation points for sentence structure: 4-no error, 3- less erorrs, 2-many errors, 0-not acceptable-->
    <items> 
      <code>grade_st</code> 
      <content>2</content>
    </items>
<!-- comment for für sentence structure -->
    <items>
      <code>grade_st_comment</code>
      <content>Here is my sentence structure comment </content>
    </items>
<!-- evaluation points for comprehension and clarity: 4-no error, 3-less erorrs, 2-many errors, 0-not acceptable-->
    <items> 
      <code>grade_cocl</code> 
      <content>2</content>
    </items>
<!-- comment for für comprehension and clarity -->
    <items>
      <code>grade_cocl_comment</code>
      <content>Here is my comprehension and clarity comment </content>
    </items>
<!-- evaluation points for follow instructions: 4-no error, 3- less erorrs, 2-many errors, 0-not acceptable-->
    <items> 
      <code>grade_foin</code> 
      <content>2</content>
    </items>
<!-- comment for für follow instructions --> 
    <items>
      <code>grade_foin_comment</code>
      <content>Here is my follow instructions comment </content> 
    </items>
<!-- evaluation points for selection of information: 4-no error, 3-less erorrs, 2-many errors, 0-not acceptable-->
    <items> 
      <code>grade_sein</code> 
      <content>2</content>
    </items>
<!-- comment for für selection of information -->
    <items>
      <code>grade_sein_comment</code>
      <content>Here is my selection of information comment </content> 
    </items>
<!-- Your comment to author. Required if text is rejected. --> 
    <items>
      <code>comment</code>
      <content>Text is ok.</content> 
    </items>
  </input> 
</job>
  • JSON Example
job: {
  input: {
    items: [{
      code: "accepted", 
      content: "1"
    },{
      code: "grade_gr", 
      content: "2"
    },{
      code: "grade_gr_comment",
      content: "Here is my grade_gr comment"
    },{
      code: "grade_sppu", 
      content: "2"
    },{
      code: "grade_sppu_comment",
      content: "Here is my spelling and punctuation comment"
    },{
      code: "grade_sest", 
      content: "2"
    },{
      code: "grade_sest_comment", 
      content: "Here is my style comment" 
    },{
      code: "grade_st", 
      content: "2"
    },{
      code: "grade_st_comment",
      content: "Here is my sentence structure comment "
    },{
      code: "grade_cocl", 
      content: "2"
    },{
      code: "grade_cocl_comment",
      content: "Here is my comprehension and clarity comment"
    },{
      code: "grade_foin", 
      content: "2"
    },{
      code: "grade_foin_comment",
      content: "Here is my follow instructions comment "
    },{
      code: "grade_sein",
      content: "2" 
    },{
      code: "grade_sein_comment",
      content: "Here is my selection of information comment" 
    },{
      code: "comment",
      content: "Text is ok." 
    }
  ]}
}

Response

Response Status

  • 200, if the request was successfully handled
  • 404, if the job does not exist or the Task does not exist.
  • 409, if the input items provided by the customer do not match the form definition

Response Body

(Idental to “View Job Details” as described above)

Tags: