Abicart API # List selection
# List methods
List selection is used to filter, limit and sort the resulting entities received when executing a list method. In many API methods for listing various entities, e.g. Article.list, Articlegroup.list, Customer.list, Customergroup.list, Order.list, a list-selection parameter is expected.
The list-selection parameter specifies which of the existing articles (or customers, etc.) to fetch. A list selection is an object containing any of the keys "filters", "limit", "offset" and "sort" with an optional "descending" boolean to change the sorting direction. Most properties (with a few expections) can be used for filtering. For all available sorting keys, see the documentation of each method.
The following example lists all the entities that have been ordered within the given timespan, sorted by unique identifier in descending order. The first 3 are skipped and the listing is limited to 100 entities.
{
"filters": {
"/ordered": {
"min": "2013-01-14T15:04:34Z",
"max": "2014-01-14T15:04:34Z"
}
},
"sort": "uid",
"descending": true,
"limit": 100,
"offset": 3
}
# Count methods
"count" is a close relative to "list". It takes a filter object (see below) and returns the number of objects found, as an integer. As a rule, all objects that can be listed can also be counted (e.g. Article.count). A difference from the list family, however, is that filter aliases such as "limit" and "offset" (see below) cannot be used here.
# Filter objects
Filter out values when executing a list (or count) method. Filters are specified using a JSON pointer to a property as the key and the conditions that should apply to it as the value. If multiple conditions are specified, then all must apply for the filter to be true. Multiple filters can be combined in the filter object to create more complex ones. The conditions that can be made are limited by the type of that property. You can use filters on most but not all of the properties.
| Type | Values |
|---|---|
| date-time | min, max |
| string | equals, in, startsWith, endsWith, contains |
| number | equals, in, min, max, less, greater |
| integer | equals, in, min, max, less, greater |
| boolean | equals |
# Examples
# Example 1
All entities changed within the timespan.
{
"filters": {
"/changed": {
"min": "2013-01-14T15:04:34Z",
"max": "2014-01-14T15:04:34Z"
}
}
}
# Example 2
All entities where firstName in the address object starts with "An".
{
"filters": {
"/address/firstName": {
"startsWith": "An",
}
}
}
# Example 3
All entities with a minimum weight of 1.
{
"filters": {
"/weight": {
"min": 1
}
}
}
# Example 4
All entities where parent is 1.
{
"filters": {
"/parent": {
"equals": 1
}
}
}
# Example 5
All entities whose parent is 1, 2, 3 or 4.
{
"filters": {
"/parent": {
"in": [
1,
2,
3,
4
]
}
}
}
# Combining multiple filter entries.
# Example 6
All entities where company starts with "Tex" and is a member of group 5.
{
"filters": {
"/groups": {
"contains": 5
},
"/info/firstName": {
"equals": "Emil"
},
"/address/company": {
"startsWith": "Tex"
}
}
}
# Example 7
All entities where company name starts with "Tex" and is a member of either group 5 or group 6.
{
"filters": {
"/groups": {
"containsAny": [4, 5]
},
"/info/firstName": {
"equals": "Emil"
},
"/address/company": {
"startsWith": "Tex"
}
}
}
# Example 8
All entities where company name contains "xtal".
{
"filters": {
"/address/company": {
"contains": "xtal"
}
}
}
# Shorthand filters
To make filtering a bit more convenient, we provide a shorthand way of specifying individual filters. If no filter operator is specified, then it defaults to the operator if the argument is a list, otherwise to the equals operator.
All entities where parent is 8.
# Example 9
# Example 10
All entities where parent is one of 1, 2 or 3.
# Example 11
All entities where name is "Emil".
# Example 12
All entities where name is one of "Emil", "Raoul" or "Viktor".
# Null properties
Some objects have properties that may or may not exist. For example, top-level article groups have no parent. To filter out such objects, use null.
{
"filters": {
"/parent": {
"equals": null
}
}
}
{
"filters": {
"/parent": {
"in": [
null,
1,
2,
3
]
}
}
}
# Filter aliases
Some filters are not of the standard format, for various reasons. Maybe they are not tied to the object via the schema or they require some special treatment in the backend so that the standard format doesn't really apply. These filter aliases are listed in the documentation of each method.
# limit
Limits the number of entities received when executing a list method. If no maximum limit is specified in the documentation of a method, then it defaults to 500.
{
"limit": 100
}
# offset
An offset can be provided to enable iteration through listings. This is needed since the number of entities returned by the list call is capped. It is also useful for when you need to paginate a listing. The default offset is 0.
{
"limit": 100,
"offset": 0
}
{
"limit": 100,
"offset": 100
}
[...]
{
"limit": 100,
"offset": n*100
}
# sort
Sorts the entities according to a predfined order. The orderings differ from method to method and are available in the documentation of the method in question. The default ordering is ascending. This can be changed by supplying a key-value pair "descending": true to the list-query object. The default ordering is the first in the list of available orderings in the documentation of each method.
# Sort entities by first name, in ascending order.
{
"sort": "firstName"
}
# Sort entities by unique identifier, in ascending order.
{
"sort": "uid",
"descending": false
}
# Sort entities by customer number, in descending order.
{
"sort": "customerNumber",
"descending": true
}