Contents

Cardmarket RESTful API Documentation (Version 1.1.1)

This is the main page for Cardmarket's RESTful API version 1.1 (v1.1.1). If you're using the API version 2.0, please refer to the 2.0 Documentation.

Introduction

Finally we're able to present you Cardmarket's RESTful API 1.1. With it we also opened the Sandbox server of Cardmarket. Here you can test your software based on the API without messing up the live data.

Read more about the Sandbox and it's requirements at the Sandbox Server Documentation.

Access the API and Authentication

With the introduction of the 1.1 version both versions of the API will run parallel on our servers.

As announced we'll drastically change the way of authenticating against the API. Once 1.1 hits the live servers, the old authentication method with username and API key will be completely switched of and only OAuth 1.0 remains active. So we decided to only go with OAuth 1.0 at the sandbox server.

Everything you need to know about our implementation of OAuth and how to use it, you'll find in the dedicated Authentication Documentation.

To create an app (either Dedicated, 3rd Party, or Widget App) login to your account at the normal website and go to your profile page. Here you'll find the option for creating one.

Types of Resources

Cardmarket API and its resources is basically parted into the following sections:

You'll find an overview description of the different requests (and the links to the detailed description) at the respective section pages.

Response Formats and Entities

With 1.1 we also introduce JSON as a response format for all requests. You can now choose between XML (still standard) and JSON. If you decide for JSON, simply use the switch output.json between the base URI and the resource URL.

Example

You'll find a list of all entities that are returned by the various requests at Entities Documentation. These entities have the same structure as the 1.0 entities, so if you still want to use API version 1.0 after 1.1 hits the live servers, you should refer to the changes, we had to made to the entities' structure to follow some changed requirements.

Response Codes

200 OK

Any successful request normally returns a 200 OK HTTP status.

206 Partial Content and 204 No Content

As announced we change the strategy of 206 Partial Content HTTP status responses. You now have full control if receiving the whole collection or only parts of it.

For more information, see 206 Partial Content Documentation

307 Temporary Redirect

There are some requests that can return this HTTP status code:

In cases you requests one of these requests unpaginated and the response would return more than 100 entities, the response is a 307 telling you to instead call a paginated request with the start parameter. This has mainly performance reasons because these requests produce a lot of work for the server and can take a long time when called unpaginated.

Attention: Some implementations try to perform a 307 Temporary Redirect instantly and without further notice. This will leed to a 401 Unauthorized (or 403 Forbidden), because the OAuth signature for the original request is not valid for the request delivered with the 307 Temporary Redirect.

400 Bad Request

Whenever something goes wrong with your request, e.g. your POST data and/or structure is wrong, or you want to access an article in your stock by providing an invalid ArticleID, a 400 Bad Request HTTP status is returned, describing the error within the content.

401 Unauthorized

You get a 401 Unauthorized HTTP status, when authentication or authorization fails during your request, e.g. your Authorization (signature) is not correct.

403 Forbidden

You get a 403 Forbidden HTTP status, when you try to access valid resources, but don't have access to it, i. e. you try to access /authenticate with a dedicated or widget app, or resources specifically written for widget apps with a dedicated app.

405 Not Allowed

You get a 405 Not Allowed HTTP status, every time you want to access a valid resource with a wrong HTTP method.

While OPTIONS requests are now possible on all of the API's resources, most resources are limited to one or more other HTTP methods. These are always specified in the Access-Control-Allow-Methods header coming with each response. Please refer to CRUD Operations Documentation to learn more about the different HTTP methods and which purposes they fulfill in a RESTful API.

412 Precondition Failed

When you want to perform an invalid state change on one of your orders, e.g. confirm reception on an order, that's still not flagged as sent, you get a 412 Precondition Failed HTTP status.

417 Expectation Failed

Typically you get a 417 Expectation Failed HTTP status code, when your request has an XML body without the corresponding header and/or the body not sent as text, but its byte representation. Another possible reason for a 417 is, when you send body data with more than 1.024 bytes without adding the header Expect: to your request.


Document written on May, 13th 2014