Overview ======== The Marktplaats and 2dehands/2ememain API is a RESTful API to place ads on Marktplaats, 2dehands.be or 2ememain.be. The content is provided in JSON format in ``UTF–8`` encoding. Multi tenant/multi locale ------------------------- The API is identical for Marktplaats and 2dehands/2ememain. This means we support two platforms which have the same semantics from an API point of view, but this doesn't mean the platforms are the same. It is only possible to place advertisements on the platform of the URL which is being used. This means it is *not* possible when using the Marktplaats API to place advertisements on the 2dehands platform and vice versa. When using the 2dehands platform, it is possible to explicitly define the locale (language) of the entity by supplying a `locale` field. This field is optional, and when omitted, the default locale is defined using the following rules in order of priority: 1. The locale specificed in the `locale` field 2. The locale specified in the preferences of the current user 3. The default locale for the current domain. This means `nl-BE` for `api.2dehands.be` and `fr-BE` for `api.2ememain.be` The API's for the 2 platforms with the allowed locales are defined below: - Platform Marktplaats: supported locales `nl-NL`, URL: `api.marktplaats.nl` - Platform 2dehands: supported locales `nl-BE` and `fr-BE`, URL's: - `api.2dehands.be` - 2dehands platform, default locale `nl-BE` - `api.2ememain.be` - 2dehands platform, default locale `fr-BE` While both platforms are supported, in the examples we mainly use Marktplaats. The functionality should be the same for 2dehands. Accept Headers -------------- Each call to resources of the API needs accept headers set. One part in that is the Media Type, as defined above. An additional part is necessary for allowing OAuth errors to be returned, in regular JSON. We recommend usage of accept headers as follows:: , application/json In case of absence of the 'application/json' part, an OAuth error such as '401: Token Expired' will not be possible to be returned since the accepted content type does not match, resulting in a '406: Not accepted' error, obfuscating the underlying issue. Our examples will also demonstrate the recommended usage. Authentication -------------- Authentication is provided using *OAuth2* to allow easy integration with existing libraries. For more information please have a look at the `OAuth 2.0 website `_. Dates and Times --------------- All date/time values are specified in `ISO 8601 Combined date and time in UTC format `_. Prices and Currencies --------------------- All monetary amounts like prices and budgets are currently in Euros and stored as euro cents. Currencies are specified as three character `ISO 4217 `_ code. HTTP Response Codes and Error Handling -------------------------------------- To retrieve, update and delete resources with the API you use the standard HTTP verbs ``GET``, ``PUT`` and ``DELETE``. If the resource exists and the request was successful the server responds with ``200 OK``. If the resource does not exist the server responds with ``404 Not Found``. To create a new resource you perform a ``POST`` request to which the server responds with ``201 Created`` and a ``Location`` header containing the URL of the new resource. All requests are validated before they are being executed by the server. If the validation fails the server responds with ``400 Bad Request`` and an error response which contains a list of the errors. More information can be found under :doc:`error-handling`. Field definitions ----------------- Field definitions of resources follow a standard table pattern. ============== ===================================================================== column name meaning ============== ===================================================================== field the name of the field (when writing) type the type of the field constraints any constraints that apply to this field that you should know about Req is this field required W is this field writable (first time write (POST)) U is this field editable (PUT/PATCH) ============== ===================================================================== HTTP PATCH Methods ------------------ When an HTTP ``PATCH`` method is called, the body should be formatted according to the `JSON Patch RFC `_. The document structure of such a requests has the following structure: ``[{"op":"", "path":"", "value":""}]`` The ``operation`` can either be ``add``, ``remove``, ``replace``, ``move``, ``copy`` or ``test``. In the API, mainly ``add``, ``remove``, and ``replace`` are supported. The ``path`` is the name of the field the operation should be applied to. For example, if one wants to change the _title_ field, the path should be ``/title``. Note the beginning forward slash, which is an indication that this should be applied to the top level field of the document. The ``value`` should be the value for the field. Value should only be specified for ``replace``, ``add`` and ``test``. For ``move`` and ``copy``, a field called ``from`` should be used to specify the source of the operation. Errors `````` .. errors:: .. error:: :http: 400 :code: invalid-patch-operation :description: The patch operation sent in the patch request is not valid. It should be one of 'add', 'remove', 'replace', 'move', 'copy', 'test'