Marketplace API Principles

Managing resources using Rest

Representational State Transfer (REST) is an architectural principle for distributed systems, such as the World Wide Web. Applications and services following the REST principle apply the following concepts:

• Every resource (and every resource type) is directly reachable using a Uniform Resource Identifier (URI4), usually a canonical URL.
• A single resource can have multiple representations, like HTML, XML, or text. This allows clients to use various tools (like browsers) to handle these resources.
• No session state is maintained on the server. Clients must provide all information necessary to handle the given request. This allows atomic operations and scalable services.

URI

Using REST, a resource is identified by a URI. A URI consists of various parts. The following example demonstrates these parts and their purpose:

https://api.clickworker.com/marketplace/v2/products/TextCreate

The following parts of the URI are static and consistent throughout a given API release. In the following examples, this part is referenced by a pattern as [context]:

• https:// identifies the protocol to use (HTTP over SSL)
• api.clickworker.com is the service host’s DNS name
• /marketplace/v2 is the service’s context, including an API version marker

The last parts of the URI are specific to the managed entities.

• /products identifies the resource type
• /TextCreate is the resource’s id (a product code in this example)

As a result, details on the product with code TextCreate are returned.

Representing Resources Using XML or JSON

As stated above, a single resource may have multiple representations. Currently, the clickworker.com Marketplace API supports Extensible Markup Language (XML) and JavaScript Object Notation (JSON). Entities may support two different view modes, automatically chosen by the system:

1. A “detail” view that represents the entity and all of its public attributes. This view is selected when an entity is requested directly.

2. An “index” view that represents the entity with a limited set of public attributes. This view is chosen when an entity is requested indirectly, e.g. as part of a collection.

Clients may call one of these representations by providing a valid HTTP Accept header:

• To request a resource as XML, the Accept header must use a MIME-type of “application/xml”
• To request a resource as JSON, the Accept header must use a MIME-type of “application/json”

When clients send json or xml documents as body of post or put requests, the Content-Type Header must be set accordingly:

• To send a XML document, the Content-Type must be set to “application/xml”
• To send a JSON document, the Content-Type must be set to “application/json”

Selecting a resource representation by using a virtual file extension (like “.xml” or “.json”) is not supported, as it violates the concept of a single resource URI.

XML documents make use of a published Document Type Definition (DTD) and optionally an XML Schema. In addition to resource-specific elements and attributes, globally defined attributes (like xml:lang) and attributes from other XML namespaces (like xlink:href) may be used.

Calling operations using HTTP methods

The Hypertext Transport Protocol (HTTP) defines 8 different request methods:

• GET
• POST
• PUT
• DELETE
• HEAD
• OPTIONS
• CONNECT
• TRACE

Of this set of HTTP “verbs,” GET, POST, PUT and DELETE are supported by the Clickworker Marketplace API. These verbs are used to call predefined operations on addressed resources.

Due to issues surrounding firewall restrictions and legacy clients, HTTP PUT and DELETE methods may be encapsulated using HTTP POST. To do this, add an additional URL parameter called “_method” to the request, using the HTTP method name in uppercase as the value.

GET: Display or index resources

Calling the GET method will produce two different results:

1. If called on a resource type instead of an identified resource, an index of available resources of the requested type will be returned. The index usually contains a reduced set of resource attributes, along with the URI of the indexed resource.

2. If called on an identified resource, the resource will be printed in detail. Usually, the request will return the HTTP status code 200 (“OK”) and contain the requested resource (or resource index) as its body. See section Calling operations using HTTP methods for details on available response codes.

Usually, the request will return the HTTP status code 200 (“OK”) and contain the requested resource (or resource index) as its body. See section Calling operations using HTTP methods for details on available response codes.

POST: Create a new resource

The POST method is used to create a new resource using the addressed resource’s type. POST must only be called on URIs specifying a resource type. To modify an existing resource, the PUT method should be used.

Usually, the request will result in an HTTP status code of 201 (“Created”) and contain details on the created resource in the response’s body.

PUT: Update an existing resource

To modify an existing resource, a PUT request must be sent to the server. The request must use the URI of the resource being modified. The resource is updated with the request’s body data, which usually contains a reduced representation of the resource. It only contains attributes that can be updated. For example, the resource identifier cannot be altered after the resource has been created.

Usually, the request will result in an HTTP status code of 200 (“OK”) and contain details on the updated resource in the response’s body.

DELETE: Remove and existing resource

To remove an existing resource, the DELETE method must be called on the resource’s URI.

Usually, the request will result in an HTTP status code of 204 (“No Content”) and an empty response body, since the resource is not available any more.

Reporting status using HTTP codes

HTTP already defines an extensive set of numeric status codes that are suitable to report the outcome of request processing. They can be divided into roughly three groups:

• Success codes
• Client error codes
• Server error codes

API operations can report the status in two different ways:

1. By using the predefined HTTP header “Status” (this is the default).
2. By encapsulating the actual operation outcome inside the Request Status entity (see section Intro - Common Response Parameters). The HTTP status code will always be 200 OK (unless a server error occurs). To enable this behavior, a special URL parameter named “suppress_http_status” must be set to value “1”.

The following tables display the status codes that are used by the Clickworker Marketplace API.

Authentication and Transport Security

The Clickworker Marketplace API uses HTTP Authentication6 (“Basic Auth”) for access control. In order to use Clickworker’s crowdsourcing services through the API, you need to be registered as a customer on www.clickworker.com.

The credentials used for API authentication are identical to the username and password used at registration. In order to be able to access the API you need to be activated as an API user by our support. In order to request API access please log in with your customer account and go to “Profile” / “API access”.

To ensure data security, Clickworker’s services require the use of Secure Socket Layers (SSL).

Verifying A Client Setup

For convenience, two variants of a dedicated “Echo” service have been made available:

• Echo incoming message without authentication required
• Echo incoming message with authentication required

Calling the Echo Service

Without Authentication

To verify the availability of our services and the client’s basic communication setup, send a plain HTTP POST request to the Echo service. Request Request URI:

Request

Request URI:

http://api.clickworker.com/api/marketplace/v2/echo/simple_echo

Request body:

XML Representation

<echo> 
  <message>${message}</message>
</echo>

JSON Representation

echo: {
  message: “${message}”
}

Request parameter:

Response

Response status:

• 200, if the request was formally correct

Response body:

XML Example

<simple_echo_response> 
  <request_status>...</request_status> 
  <echo>
    <message>Your Message</message> 
  </echo>
</simple_echo_response>

JSON Example

simple_echo_response: { 
  request_status: ..., 
  echo: {
    message: “Your Message” 
  }
}

With Authentication

Calling the echo service with authentication not only verifies basic client/server communication, but also ensures the validity of the customer’s account.

Technically, the procedure is identical to the one without identification with one major difference: Clients must use an SSL HTTP (https) POST request.

Request

Request URI:

https://api.clickworker.com/api/marketplace/v2/echo/extended_echo

Request body:

XML Representation

<echo> 
  <message>${message}</message>
</echo>

JSON Representation

echo: {
  message: “${message}”
}

Request parameter:

Response

Response Status:

• 200, if the request was formally correct

Response Body

XML Example

<entended_echo_response> 
  <request_status>...</request_status> 
  <echo>
    <message>Your Message</message> 
  </echo>
</extended_echo_response>

JSON Example

extended_echo_response: { 
  request_status: ...,
  echo: {
    message: “Your Message” 
  }
}