Version 1.1 is deprecated and will be disabled in September 2021.
Refer to the API 2.0 Migration Guide.
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.
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.
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.
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.
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
GET https://sandbox.mkmapi.eu/ws/v1.1/games will return Cardmarket's supported games as XML (because XML is standard).GET https://sandbox.mkmapi.eu/ws/v1.1/output.xml/games will return Cardmarket's supported games as XML.GET https://sandbox.mkmapi.eu/ws/v1.1/output.json/games will return Cardmarket's supported games as JSON.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.
Any successful request normally returns a 200 OK HTTP status.
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
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.
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.
You get a 401 Unauthorized HTTP status, when authentication or authorization fails during your request, e.g. your Authorization (signature) is not correct.
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.
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.
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.
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