Gambio REST API v3

Download OpenAPI specification:Download

This documentation reference will provide you analytic guides on how the API works, which resources are available and the proper way to request them efficiently.

We follow a strict deprecation period for breaking changes to our endpoints, so that appropriate time is given to users to update their implementations accordingly.

Thank you for using the Gambio GX3 API!

Authentication

basicAuth

Every request of the API needs to be authenticated otherwise a 401 Unauthorized response will be returned. The client will need to use the administrator user's credentials through the HTTP Basic Auth header. You can read more about the HTTP authentication header here.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

bearerAuth

The API also supports the usage of JSON web tokens, which can be generated on the CustomersRoles and Permissions page of the Gambio Admin.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

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:

{
  //...
  "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

ImageLists

The following endpoints can be used to manage the image lists of this shop.

The shown paths of the API endpoints are relative paths and references the <shop-root>/images/product_images/original_images directory. E.g. the image path tshirds/red.jpg references the <shop-root>/images/product_images/original_images/tshirds/red.jpg file.

Get all available image lists

Returns a collection of image lists.

Authorizations:
query Parameters
fields
string
Example: fields=id,customer,orders.id

Optional query parameter for trimming the provided documents. Parameter represents a comma separated list of attributes.

filter
object
Example: filter[customer.gender]=d&filter[customer.firstName]=max&filter[customer.lastName]=muster*&filter[customer.age]=gte|18&filter[date]=lt|2020-02-01

Optional query parameter for filtering. Parameter represents an object, which is used to filter the provided documents.

page
integer >= 1
Default: 1
Example: page=2

Optional query parameter to define current page.

per-page
integer [ 1 .. 100 ]
Default: 25
Example: per-page=25

Optional query parameter to limiting the provided documents.

sort
string
Example: sort=-creationDate,+customer.firstName

Optional query parameter for sorting. Parameter represents a comma separated list of attributes.

Responses

Response Headers
X-Shop-Version
string
Example: "4.1.0.0"

Current shop version.

X-API-Version
string
Example: "3.0.0"

Current API version.

X-Rate-Limit-Limit
integer
Example: 5000

Request limit per time frame.

X-Rate-Limit-Remaining
integer
Example: 4242

Number of requests left for current time frame.

X-Rate-Limit-Reset
integer
Example: 3500

Seconds til the current rate limit resets.

Response Schema: application/json
Array of objects (imageLists-imageLists)
object (imageLists-collectionMetaData)

Response samples

Content type
application/json
{}

Create a new image list

Creates a single or multiple new image lists based on the request body.

Authorizations:
Request Body schema: application/json

Image lists data for creation.

Array ()
name
required
string non-empty

Responses

Response Headers
X-Shop-Version
string
Example: "4.1.0.0"

Current shop version.

X-API-Version
string
Example: "3.0.0"

Current API version.

X-Rate-Limit-Limit
integer
Example: 5000

Request limit per time frame.

X-Rate-Limit-Remaining
integer
Example: 4242

Number of requests left for current time frame.

X-Rate-Limit-Reset
integer
Example: 3500

Seconds til the current rate limit resets.

Response Schema: application/json
data
Array of integers <int32> (imagelists-imagelistIds)
object (imageLists-creationMetaData)