Rest API

The real.de Onlineshop REST API is an HTTP interface to the real.de Onlineshop product data. It allows you to search the site, retrieve information about products, and manage your own inventory and sales. This page provides a general overview of the real.de Onlineshop API and the endpoints documentation page provides detailed information about each of the available API endpoints.

Overview

Requirements

Before you start make sure that you have both a Client Key (a 32 character string) and Secret Key (a 64 character string). If you have not already received these keys from real.de Onlineshop, or you have lost your keys, you can generate new ones on your API settings page.

Examples:

Client Key: 7bffc16ba2cc5ac1cbf527d6fa39263

Secret Key: a7d0cb1da1ddbc86c96ee5fedd341b7d8ebfbb2f5c83cfe0909f4e57f05dd403

Warning: Do not lose your API keys. For security, they cannot be retrieved if they are lost. If you lose them, you will have to generate new ones on your API settings page.

Sending Requests

General Information

In order to interact with the API, you must send an HTTPS (SSL encrypted) request to one of the available API endpoints. All requests must contain several HTTP headers (see below). Some of the API actions require use of the PATCH or POST verbs, and the body of those requests must be in a valid JSON format.

Required Headers

Each request must contain 4 headers:

Signing Requests

Each request must be signed by a SHA-256 HMAC in base64 encoding. This HMAC is generated by concatenating the request information together, separated by newline characters, and generating a SHA-256 HMAC from the resulting string and your Secret Key.

Here is an implementation of the HMAC generation function in PHP:

function signRequest($method, $uri, $body, $timestamp, $secretKey)
{
	$string = implode("\n", [
		$method,
		$uri,
		$body,
		$timestamp,
	]);

	return hash_hmac('sha256', $string, $secretKey);
}

The required values in the signature string are:

The PHP function hash_hmac() produces an HMAC using SHA-256 as the cryptographic hash function.

For example, you could generate an HMAC for the following values (again, in PHP):

$method = "POST";
$uri = "https://www.real.de/api/v1/units/";
$body = "";
$timestamp = 1411055926;
$secretKey = "a7d0cb1da1ddbc86c96ee5fedd341b7d8ebfbb2f5c83cfe0909f4e57f05dd403";

The correct HM-Signature generated by these values is:
75312eabe66e4b9e74552a5e8959456d69cfa52a7cae9049093aede4bcdf71e7.

Here is the same function written in several different languages, along with a full test program:

Signature function

function signRequest($method, $uri, $body, $timestamp, $secretKey)
{
	$string = implode("\n", [
		$method,
		$uri,
		$body,
		$timestamp,
	]);
	
	return hash_hmac('sha256', $string, $secretKey);
}

Full example

Signature function


import hmac
import hashlib

def sign_request(method, uri, body, timestamp, secret_key):
	plain_text = "\n".join([method, uri, body, str(timestamp)])
	
	digest_maker = hmac.new(secret_key, '', hashlib.sha256)
	digest_maker.update(plain_text)
	return digest_maker.hexdigest()

Full example

Signature function


import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.xml.bind.DatatypeConverter;
import java.security.NoSuchAlgorithmException;
import java.security.InvalidKeyException;

public static String signRequest(String method, String uri, String body, long timestamp, String secretKey)
	throws NoSuchAlgorithmException, InvalidKeyException {
	
	String plainText = method + "\n" + uri + "\n" + body + "\n" + timestamp;
	
	Mac mac = Mac.getInstance("HmacSHA256");
	SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
	mac.init(secretKeySpec);
	
	byte[] rawHmac = mac.doFinal(plainText.getBytes());
	return DatatypeConverter.printHexBinary(rawHmac);
}

Full example

Note that the Secret Key is always a string that just happens to look like a hexadecimal number. Do not interpret it as a hex value, or you will generate the wrong signature!

Reading Responses

Responses from the real.de Onlineshop API can either have an empty body or contain a UTF-8 encoded JSON string in the body. Only GET operations respond with a non-empty body. When a body is sent, the Content-Type of the response will be application/json.

JSON responses may have one of two formats:

An example of an Object response:

{
	"id_category": 21,
	"name": "parfuem",
	"id_parent_category": 11,
	"title_singular": "Parfüm",
	"title_plural": "Parfüms",
	"level": 2,
	"url": "https://www.real.de/parfuem/",
	"shipping_category": "D",
	"variable_fee": "8.50",
	"fixed_fee": 0,
	"vat": "19.00",
	"parent": {
		"id_category": 11,
		"name": "koerperpflege-und-gesundheit",
		"id_parent_category": 1,
		"title_singular": "Körperpflege & Gesundheit",
		"title_plural": "Körperpflege & Gesundheit",
		"level": 1,
		"url": "https://www.real.de/koerperpflege-und-gesundheit/",
		"shipping_category": "D",
		"variable_fee": "12.50",
		"fixed_fee": 0,
		"vat": "19.00"
	}
}

An example of a Collection response:

[
	{
		"id_category": 39231,
		"name": "laptops-und-zubehoer",
		"id_parent_category": 39161,
		"title_singular": "Laptop & Zubehör",
		"title_plural": "Laptops & Zubehör",
		"level": 4,
		"url": "https://www.real.de/laptops-und-zubehoer/",
		"shipping_category": "D",
		"variable_fee": "5.90",
		"fixed_fee": 0,
		"vat": "19.00"
	},
	{
		"id_category": 46051,
		"name": "laptops",
		"id_parent_category": 39231,
		"title_singular": "Laptop",
		"title_plural": "Laptops",
		"level": 5,
		"url": "https://www.real.de/laptops/",
		"shipping_category": "D",
		"variable_fee": "5.90",
		"fixed_fee": 0,
		"vat": "19.00"
	}
]

Collection Pagination

Some API requests may return very large Collections of values. For example, you may have thousands of units for sale on the real.de Onlineshop, and a GET /units/ request would attempt to return all of them.

To make the responses more manageable, the results will be split into smaller groups or pages. Which page is returned in the response and how many Objects it contains are controlled by the limit and offset GET parameters. The default and maximum limit are endpoint dependent and are listed for each endpoint on the endpoint documentation page in the "Description" column. The default offset is always 0.

Examples:

Each response which returns a Collection in the body also includes an additional HTTP header HM-Collection-Range, which describes the total number of items and currently selected range. The header has the format HM-Collection-Range: ${start}-${end}/${total}.

For example, in response to the request GET /categories/?limit=25&offset=5, the server will return the header HM-Collection-Range: 6-30/5530. This means that the total number of categories is 5530, but the response only contains categories 6 to 30. If the response contains an empty collection, the header will look like HM-Collection-Range: 0-0/5530. If you are familiar with SQL, the offset and limit query parameters behave just like the OFFSET and LIMIT SQL keywords.

Embedded Values

By default the API returns a default group of fields for each Object, but some endpoints allow optionally requesting additional fields. For example, when getting information about a single product (see code example below) it's possible to embed the product's category and units in the Item object. These optional fields are controlled through the embedded GET parameter, which contains a comma-separated list of desired additional fields.

For example, the request GET /item/20574181?embedded=category,units will return the item Object with the "category" property set to the item's category Object and the property "units" set to the the item's Collection of units.

Endpoints

All endpoints in the real.de Onlineshop API require HTTPS encryption and start with https://www.real.de/api/v1/. You can view documentation for the endpoints on the endpoints documentation page. This page also allows you to execute API requests directly from the documentation. Just fill in your Client Key and Secret Key in the fields at the top of the page and click Explore. Then you can expand any of the endpoint descriptions, fill in the fields, and click the "Try it out!" button. This will perform an API request to the server and display the results in the page.

Code Examples

For full code examples, see the Code Examples page.