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 GX4 API!
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 Customers
→ Roles and Permissions
page of the Gambio Admin.
Security Scheme Type | HTTP |
---|---|
HTTP Authorization Scheme | bearer |
Bearer format | "JWT" |
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
.
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 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.
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.
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.
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 nameJohn
. - GET
/api.php/v3/withdrawals?filter[customer.firstName]=J*
will return all withdrawals of customers whose first name begins withJ
. - GET
/api.php/v3/withdrawals?filter[customer.firstName]=J*&filter[id]=*1
will return all withdrawals of customers whose first name begins withJ
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 than42
. - GET
/api.php/v3/withdrawals?filter[id]=gte|42
will return all withdrawals with an ID that is equals or greater than42
. - GET
/api.php/v3/withdrawals?filter[id]=lt|42
will return all withdrawals with an ID that is less than42
. - GET
/api.php/v3/withdrawals?filter[id]=lte|42
will return all withdrawals with an ID that is equals or less than42
. - GET
/api.php/v3/withdrawals?filter[id]=neq|42
will return all withdrawals with an ID that is not equal to42
. - 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 of2020-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
The following endpoints can be used to manage the currencies of this shop.
Currently, the shop does only support endpoints to read currencies.
Get all available currencies
Returns a collection of currencies.
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]=o&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
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 (currencies-currencies) | |
object (currencies-collectionMetaData) |
Response samples
- 200
{- "data": [
- {
- "id": 1,
- "name": "Euro",
- "code": "EUR",
- "symbols": {
- "left": "",
- "right": "EUR"
}, - "value": 1,
- "decimalSeparator": ",",
- "thousandsSeparator": ".",
- "decimalPlaces": 2,
- "isDefault": false
}
], - "_meta": {
- "totalItems": 42,
- "totalPages": 2,
- "perPage": 25,
- "page": 2,
- "links": {
}
}
}
Get a specific currency
Returns a single currency based in the provided ID.
Authorizations:
path Parameters
currencyId required | integer >= 1 Example: 1 ID of an existing currency. |
Responses
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
object (currencies-currency) | |
object (currencies-documentMetaData) |
Response samples
- 200
{- "data":