REST API

The Allegro platform provides customers with API features based on the REST architecture. For this purpose it uses the HTTP protocol and its methods: GET, POST, PUT, DELETE. Allegro platform elements have been divided into resources (e.g. /offers, /users, /categories, etc.). You can access them by calling a selected HTTP method at https://allegroapi.io, adding a path to a selected resource.

Example of loading information on Allegro category with identifier 2:

GET https://allegroapi.io/categories/2

If you want to load more than one resource, do not enter the identifier in the path. Example loading of Allegro category list:

GET https://allegroapi.io/categories

HTTP methods

Each of the API resources can use the following HTTP methods:

GET: Used for data loading. All GET methods can be called several times, because they do not modify any Allegro resources.

POST: Used for creating a new resource (e.g. creating a new offer results in a resource of the offers type). ). If the POST method is called twice on the offers resource, two offers will be listed on Allegro.

PUT: Used for editing a resource (e.g. editing a description of an Allegro offer). It is secure to call the PUT method twice on the same resource.

DELETE: Used for deleting resources.

Communication protocol

REST API can be accessed by HTTPS connection to the allegroapi.io server. All data sent and loaded from the server is in the JSON format.

Each response contains e.g. Trace-id header whose value clearly identifies the customer’s HTTP query. If a problem is reported with the HTTP query, it is necessary to provide Trace-Id in the request.

Data representation (JSON)

All data is sent and loaded from API in the JSON format . The basic element of this format is a field whose name is separated by a colon from the field value. Fields are separated by a comma. A JSON object is another element, enclosed in double curly brackets. Tables in the JSON format are saved using square brackets.
Empty fields (with null value) are each time attached to the response – they are not hidden.

Access to API

Authentication and authorization

Most REST API resource requests require an OAuth token to be provided in the Authorization header.

All incoming requests to Allegro API need to have the Api-Key header with a key responsible for identification of the application using API. You will receive an API key after registering your application..

Parameters

A number of API methods can accept optional parameters. HTTP queries of the GET type accept parameters placed in the address of the resource which the query refers to. If a parameter name corresponds to the field inside the object, parts of this name are separated by dots:

https://allegroapi.io/categories?parent.id=2

Other HTTP query types, such as POST and PUT, have parameters placed in the query itself, and not in the address:

DELETE queries do not accept parameters placed in their contents, but it may happen that they will accept parameters in the resource address.

Resource versioning

REST methods are versioned. Any changes to them violating backwards compatibility are introduced to new method versions. When calling the method, you need to enter a resource version number (which can be viewed in the method documentation).

Choose the method version by setting e.g. v1 in the Accept or Content-Type headers.:

Accept: application/vnd.allegro.public.v1+json

Exceptions include DELETE and end-point OAuth methods (https://allegro.pl/auth) which are not versioned.

Beta version methods

Beta version methods are resources we are still working on. They may not be fully functional, may be often changed and violate backwards compatibility. We advise not to use them in live systems..

A method in its beta version is marked similarly to a live version. The only difference is that data type contains the beta word:

message: Internal information about an error for software developer. It makes it easier to find the reason for the problem.

code: Error code represented as a string. On its basis an application can decide whether an error requires special handling (e.g. presenting a CAPTCHA dialogue if an incorrect access password is entered).

userMessage: Information on an error, friendly for an application user; in most cases, this error will be addressed by presenting a field message to the user.

path: Path to the field containing an error (it is shown for field validation and parameter errors).

details: Error details (if available).

Pager

To load a specific result list page, you need to use two parameters:

offset: it defines a number of a batch of returned data and is numbered from 0.

limit: It defines a number of elements on the page, which cannot be higher than the maximum limit supported by the resource.

Example of loading the first batch of offers:

GET /offers?offset=0&limit=100

Example of loading another batch of offers:

GET /offers?offset=100&limit=100

Filtering options

Resources available in API may filter in two ways:

Basic, which involves sending field names to be filtered in parameters placed in the resource address (query parameters):

/offers?offer.title=iphone

Advanced, which requires more steps to be taken.

There is a POST resource which creates filters to search objects. This resource name consists of two parts separated by a hyphen; the first one corresponds to the main resource name and the second one is the searches word:

POST /offer-searches

You need to send a filter definition in the query to the resource creating the filter. Afterwards, the resource will place the Location header with a filter ID in response to the customer. This ID should be sent to the main resource in the search.id parameter in the resource address, using the GET method:

GET /offers?search.id=filter_id

In addition, you can load filter data using the GET method on the filter resource:

GET /offer-searches/filter_id

Sorting options

To start searching with sorting options, you need to send the sort parameter when calling a resource (assuming that the resource supports sorting of its result list). If the sorting result is to be reversed, the field name should be preceded with a dash. If the result is to be sort by more than one field, you need to send a list of fields separated by commas in the parameter.

Example of loading an offer list sorted by Buy it Now price:

GET /offers?sort=buyNow

Example of loading an offer list sorted in descending order by Buy it Now price:

GET /offers?sort=-buyNow

Example of loading an offer list sorted first by Buy it Now price and, then, by the offer creation date:

Resource IDs

API returns resource identifiers always as a string of characters, mostly in the UUID format. We recommend that identifiers be stored in strings, even if API returns a number in inverted commas as an identifier, because it may change in the future.

Przykład:

"bg645d84-75b4-431b-adb2-eb6b9e546059"

Limiting the number of queries (limits)

In Allegro REST API (in its live and test versions) there are two main limits imposed on:

key API (Api-Key)

9000 queries per minute

IP address

120 queries per second.

If any of the above limits is exceeded:

the API key or the IP address is blocked for 5 minutes (depending on which limit was exceeded),

a response is returned with the following status: 429 Too Many Requests.

After the expiry of the specified time limit, the access to the service from the API key or IP address is restored automatically.

Test environment

It is possible to test REST API on the WebAPI test environment, i.e. WebAPI Sandbox. Owing to this solution, you can test both Allegro programming interfaces on one environment.

Contrary to WebAPI, limits and restrictions are identical for live and test environments.

WebAPI Sandbox technical downtimes

Additionally, to ensure the functioning of test environment of sufficient quality, we carry out periodic technical works resulting in the interruption in access to the environment and permanent deletion of all data created earlier on Sandbox (offers, transactions, feedback, payments, etc. and registered REST API applications). The only data that may be restored concerns users and WebAPI keys assigned to them, generated in the WebAPI tab in My Allegro on the live environment.

The downtime is each time announced in News on the WebAPI information page and on our Forum.