shopping24 documentation

s is for shopping

Getting started: API

Well. Getting started with the API is pretty easy. We speak HTTP and REST. In order to retrieve data from the API, you need a so called appid and appkey:

appid: Your application identifier
appkey: Your secret access key.
appcore: The application identifier you request data for. This is usually your appid and part of the API url.

You will supplied with those by our Sales & Account Management Team. For easy testing, you can visit the following api preview page and browse your application, preview api requests and visualize your results.

API preview

Requesting data

Access to the API is authenticated. Use basic authentication with your appid as username and your appkey as password.

$ curl -u "appid:appkey" https://api.s24.com/v3/:appcore

Non-authorized requests will result in a 401 Unauthorized HTTP status code. Unauthorized requests (e.g. invalid credential / product core combination) result in a 403 Access HTTP status code.

When using basic authentication, username and password are transferred (almost) readable over the wire. Please use the SSL endpoint when communicating with the API.

Distinguish content type

By default, the API returns application/xml as content type. You can distinguish your desired content type by setting the HTTP Accept header to one of the following:

application/xml: The default product representation is XML, text/xml is a synonym.
application/json: Returns product representation in JSON format.
application/javascript: Enables JSON-P callbacks from Javascript applications. Synonyms are application/x-javascript and text/javascript. The GET parameter to specifiy the callback method is callback, defaults to callback().

Compression

You can request compressed data by adding a Accept-Encoding: gzip header to your request. The response will be returned gzipped.

Retrieving data

Expect these HTTP return codes from the API.

200 OK: Standard response for successful HTTP requests.
204 No Content: Is sent upon a successful HTTP request which did not produce any output.

Client error codes

All client (and server) error codes include a detailed message in the message body. The message is marshaled according to your Accept HTTP header (XML or JSON).

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<error>Authentication required</error>

400 Bad Request: Issued by sending invalid parameter values. See message body for details.
401 Unauthorized: The request was missing valid authentication credentials.
403 Forbidden: You did not have the appropriate permissions on the given resource. If you feel this is an error, contact sales or technical support.
404 Not Found: The requested resource does not exist.
405 Method Not Allowed: The request used a illegal HTTP method. Allowed methods throughout the API are GET, HEAD and OPTIONS (for the root resource).
406 Not Acceptable: The requested mime type cannot be rendered. See section distinguish content type above.

API debugging headers

The following headers are added to the query response for debugging purposes.

X-S24-Cached: Whether the request has been delivered from the cache (true)

Caching API responses

Every API response provides a Cache-Control header including information about how long or until when the response may be cached. API responses must not be cached beyond the given cache time. If request was cached internally, a X-S24-Cached: true header is present in the api response:

Cache-Control: max-age=300, must-revalidate

Checking availability

You can check the availability of the shopping24 api by checking the following url. It should reply with pong and a HTTP 200 OK header if everything is working properly.

http://api.s24.com/v3/:appid/ping