Skip to content

REST API

General Information

Since GX v4.1.1.0 there is a new REST API version available. Similar to the existing v2 API, the new endpoints can be called via https://www.your-shop-domain.de/path-to-shop/api.php/v3.

Error Handling

Every error response will contain a valid HTTP Status Code. The response body itself will provided error information based on the current mode of the application (develop or production). If there is a .dev-environment file exists in the base directory of the shop, the develop mode is active and the response body will contain not only a error message itself, but also a stack trace of the error.

HATEOAS Support

HATEOAS stands for Hypermedia as the Engine of Application State and describes the use of links which point to external resources or actions that are related to a specific resource. The API will provide links inside the response body, if available.

HTTP Caching Support

Web caching is not currently supported by any resource but is planned for a future release of the API. Caching support will be stated in each section explicitly and the API will return an ETag or Last-Modified along with an Expires headers, containing information about the provided response.

Usage with Postman

Postman is a third party graphical user interface to easily communicate with RESTful APIs. It enables you to directly import the swagger-defined GX4 API v3 specification, which we provide for you (link is at the top of this page).

Importing the specification into Postman automatically provides you with all API-Endpoints available and additionally, most variables are already declared, allowing you to quickly explore the GX4 RESTful API v3.

Defining your API location

Once you downloaded the swagger.json, it is advised to manually re-define your API's location according to your hosting. To do so, open the previously downloaded swagger.json with a text-editor of your choice, and you will see a JSON document defining all of the API's available communication.

To quickly customize the specification to your needs, change the following values at the beginning of the document by replacing the string https://www.gambio-shop.de/shop1 according to your setup:

json { //... "servers": [ { "url": "https://www.gambio-shop.de/shop1" } ], //... }

Importing into Postman

Once the above stated changes were manually applied, you may proceed to open Postman. Navigate to File -> Import... in Postman's top menu bar. Once clicked, a dialog will open asking you to specify what to import. Either drag the edited swagger.json into the dialog, or click the Choose Files button and point Postman to the document. Once the API's swagger.json was imported into postman, you will have a Postman collection called Gambio REST API v3 available, allowing you to quickly dive into the Gambio GX4 RESTful API v3.

Optional Query Parameters

There are some optional query parameters, that can be used for endpoints that generally return a collection of documents.

Note: The attributes that can be used for the following actions, are the same like the attributes of the documents in the HTTP response. A dot . can be used to address attributes in on a deeper level.

Filtering

You can filter the documents of a collection by using the query parameter filter like:

  • GET /api.php/v3/withdrawals?filter[customer.firstName]=John will return all withdrawals of customers with first name John.
  • GET /api.php/v3/withdrawals?filter[customer.firstName]=J* will return all withdrawals of customers whose first name begins with J.
  • GET /api.php/v3/withdrawals?filter[customer.firstName]=J*&filter[id]=*1 will return all withdrawals of customers whose first name begins with J and withdrawal IDs will end with an one.
  • GET /api.php/v3/withdrawals?filter[id]=gt|42 will return all withdrawals with an ID that is greater than 42.
  • GET /api.php/v3/withdrawals?filter[id]=gte|42 will return all withdrawals with an ID that is equals or greater than 42.
  • GET /api.php/v3/withdrawals?filter[id]=lt|42 will return all withdrawals with an ID that is less than 42.
  • GET /api.php/v3/withdrawals?filter[id]=lte|42 will return all withdrawals with an ID that is equals or less than 42.
  • GET /api.php/v3/withdrawals?filter[id]=neq|42 will return all withdrawals with an ID that is not equal to 42.
  • GET /api.php/v3/withdrawals?filter[date]=eq|2020-04-05 or GET /api.php/v3/customers?filter[date]=2020-04-05 will return all withdrawals with a withdrawal date of 2020-04-05.
  • GET /api.php/v3/withdrawals?filter[createdByAdmin]=1 will return all withdrawals that have been created by an admin.

Sorting

The sorting order can be modified by using the query parameter sort. This parameter always expects a comma separated list of the document attributes. A + (ascending) or - (descending) at the beginning of a attribute can be used modify the order. If no specific order is provided than a ascending order should be used.

Example: /api.php/v3/withdrawals?sort=-customer.firstName,+customer.lastName

Pagination

The query parameters page and per-page can be used for pagination.

Example: /api.php/v3/withdrawals?per-page=5&page=3

Trim documents

Endpoint providing a collection of specific documents (like /api.php/v3/withdrawals), offer the possibility to reduce the amount of information inside the provided documents. By using the query parameter fields you are able to provided a comma separated list of document attributes, which describe the structure of the returned documents.

Example: /api.php/v3/withdrawals?fields=id,customer.firstName,customer.lastName