Home

Introduction

The DaWanda API provides a simple RESTful interface with XML and JSON response formats. The API reveals a lot of DaWanda’s website information such as public user-profiles, shops, products and categories. This document provides information concerning the integration of the DaWanda API into custom web applications.

Concepts

Authentication

The DaWanda API requires an api key which can be activated here. The key is a 40 character SHA1 hash which identifies you as a unique API user and is used to track your requests. At the moment, the DaWanda API enables you to access public information. That makes an additional login process unnecessary.

HTTP Requests

The DaWanda API is based on a RESTful interface that can be used with standard HTTP GET calls. You can generate those HTTP requests with your browser or with a programming language of your choice, e.g. PHP, Ruby, Java, etc.

HTTP Status Codes

The DaWanda API uses standard HTTP status codes to indicate the sucess or failure of your API request. Status codes are part of a HTTP response. A good page for HTTP status codes is the W3C reference page, which can be found here. For a description of all possible status codes please read the section Standard Response Codes which can be found below.

Request throttling

To avoid an overload of requests we established a request throttling. DaWanda API clients are allowed to make 1000 requests per hour. If you want to make more requests with your application, contact us at [email protected]. Please send a description of your application and a rough estimation of how many requests you are expecting.

Pagination of results

The default size of a returned result is 10, the maximum is 100. If you search for all products of a specific user, the API will return 10 products as a default. If you want a larger number of returned results with one request you can specify individual parameter settings using the following query parameters: count, page or per_page. By specifying these parameters you can navigate through large sets of results more easily.

Multiple Languages

DaWanda supports 7 lanuages: German, English, French, Spanish, Dutch, Polish and Italian. To obtain the requested information (e.g. product, category) in a specific language you need to change the request domain. If you would like to receive a product’s desciption in English just set the request Domain to en.dawanda.com. Other possible values are de.dawanda.com for German translations and fr.dawanda.com for French translations.

How to make a request to the DaWanda API

Here is a step-by-step example of how to make a request to the DaWanda API. We will make a request to get details for a fictional user called “testusername” using the getUserDetails method. If you read through the documentation for that method, you will see something like this:

/users/{user_id}

resource-wide template parameters

parameter	value	description
user_id	string (required)	user_id or name

HTTP Method: GET

getUserDetails

Sample request

available response representations:

• UserType (Status Code 200 – application/xml – UserType)

potential faults:

• NotFound (Status Code 404 – application/xml – NotFound)
• NotAuthenticated (Status Code 401 – application/xml – NotAuthenticated)
• NotProcessable (Status Code 406 – application/xml – NotProcessable)

Every DaWanda API request begins with the base URL.

http://de.dawanda.com/api/v1/

The standard HTTP protocol on TCP Port 80 is used. It is followed by the sublevel domain which determines the response’s language. The domain name is dawanda and the toplevel domain is always “.com”. The API is accessed by the path prefix “/api/v1” which states the API’s version. If there will be another version in the future it might be available as “/api/v2”. Dependend on what language you prefer you can change the subdomain to one of the following values: en, fr, de

The request URI ends with the URI for the command. The part of the URI which reads {user_id} is an embedded parameter—you will need to substitute it either with the user name “testusername” or the ID of the user you are trying to access:

http://de.dawanda.com/api/v1/users/testusername

After the username you type in a period (“.”) and the format which you would like the response to be in, e.g. xml, js or json.

http://de.dawanda.com/api/v1/users/testusername.xml or http://de.dawanda.com/api/v1/users/testusername.json

Finally, you have to add a question mark (“?”) plus any optional parameters you would like to send and of course, your API key. The final request looks like this:

http://de.dawanda.com/api/v1/users/testusername.xml?api_key=YOUR_API_KEY

You can try this in your own browser. The response should be a xml document. Note that the object returned is of resource type user. Please see section Representations for details on this resource.

Sample Request from PHP

Here is an example of a PHP script request. You can use any language that supports HTTP requests (JavaScript, Ruby, Perl, Python,…) which is just about every language used on the web.

$url = “http://de.dawanda.com/api/v1/users/testusername.xml?api_key=<your_API_key>”;
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response_body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if (intval($status) != 200) die(“Error: $response_body”);

Sample Response

Here is the response from our request above. The response is formatted using XML.

<response>
<params>
<api_key>YOUR_API_KEY</api_key>
<id>testusername</id>
<format>xml</format>
</params>
<entries>1</entries>
<pages>1</pages>
<type>user</type>
<result>
<user>
<name>John Doe</name>
<city>N.Y.</city>
<is-seller type=“boolean”>true</is-seller>
<id type=“integer”>1</id>
<sex>male</sex>
<images type=“array”>
<image>
<image-40×40>http://img.dawanda.com/User/0/1/mini_avatar/1207752962-520.jpg</image-40×40>
<image-80×80>http://img.dawanda.com/User/0/1/avatar/1207752962-520.jpg</image-80×80>
</image>
</images>
<restful-path>/users/1</restful-path>
<transaction-sold-count type=“integer”>11</transaction-sold-count>
<bio>Amnesia, not much to tell about me!</bio>
</user>
<result>
</response>

The response consists of an xml document, containing the parameters which were used in the request. If applicable there will be some additional parameters with their corresponding default values. The entries tag contains the amount of entries which exists in total. If you request the products of a shop, this would be the total amount of products, even though there are just a few included in the result tag. The pages tag contains the amount of pages that exist. Given there are 10 results on one page, and 100 entries, this value would be 10. The result tag contains the resource with all its attributes.

Sample Request with jQuery

Besides results in XML and JSON format, you can request the DaWanda API in a special way to get the result according to the JSONP conventions. The response is a formatted string.

$.ajax({
dataType: ‘jsonp’,
data: “?api_key=”+dawanda_api_key,
jsonp: ‘callback’,
url: “http://de.dawanda.com/api/v1/shops/dawanda-merchandise/products.js”,
success: responseFinished
});

function responseFinished(data) {
// your code here
}