@designeo

# Api Bundle Usage

# Limit and offset

limit

  • query parameter limit=100
  • max number of results being fetched (It is a REALLY bad practice not to use limit in requests leading to frozen server and browser. This sin is punishable by listening to Justin Bieber songs.)

offset

  • skip first n items of the result, used for pagination
  • query parameter offset=200

# Filters and sort

For filter and sort we use the same key, which is equivalent of a path to the field in ApiRef/DTO.

Filter/sort path for field, which is:

  • top level field - name
  • nested field - group.name
  • nested entity primary key - group.id (short version without .id is deprecated and will not be supported)

# Filter

query parameter: fields[email][o]=valuesLike&fields[email][v]=example.com

Available filters:

  • valuesLike - text search, case insensitive
  • valuesLikeCS - text search, case sensitive
  • valuesEqual - search for one exact value from array of values
    • example with single value: ?fields[firstName][o]=valuesEqual&fields[firstName][v]=20
    • example with more values: ?fields[firstName][o]=valuesEqual&fields[firstName][v][]=john&fields[firstName][v][]=carl
  • valueNotEqual - not matching the value
  • valuesMemberOf - match related entity
    • example with single value: ?fields[countries][o]=valuesMemberOf&fields[countries][v]=20
    • example with more values: ?fields[countries][o]=valuesMemberOf&fields[countries][v][]=20&fields[countries][v][]=21
  • valueGreaterOrEqual
  • valueLowerOrEqual
  • valueNull
  • valueNotNull
  • valueEqualCI
  • valueDateRange - fields[date][o]=valueDateRange&fields[date][v][from]=2020-10-05T00:00:00Z&fields[date][v][to]=2020-10-07T00:00:00Z
  • valueNumeric
  • valueExpandedText

# Deprecated filters

  • valueEqual - search for exact value
    • replaced with valuesEqual, can be used the same way

# Sort

Default sort dir is ASC, for desc use minus -, for example -email for sorting by email DESC

Example - sort by top level field ASC, by nested field DESC and by nested entity id ASC:

  • query parameter sort=email,-group.name,group.id

https://dev.cestovka.bumbu.designeo.cz/api/v1/admin/suppliers?_envelope=1&sort=email,-group.name,group.id&limit=100&offset=0

# Validation

Invalid filter usage produces validation errors, for example:

{
  "identifier": "FILTER_ERROR_EXCEPTION",
  "errors": [
    {
      "code": "dcb91313-fa23-aeb4-94e6-ac95e930e86a",
      "message": "Field 'name' is not correctly used. Please contact support.",
      "name": "FILTER_FIELD_WRONG_USAGE_EXCEPTION",
      "property": null,
      "parameters": {
        "%fieldName%": "name"
      }
    },
    {
      "code": "2205e4c5-859c-4347-236e-f85e8c283685",
      "message": "Cannot filter by field 'nameXX'.",
      "name": "FIELD_NOT_FILTERABLE_EXCEPTION",
      "property": null,
      "parameters": {
        "%fieldName%": "nameXX"
      }
    },
    {
      "code": "86adf2ea-cde9-b439-8fbf-c78abb87e2bb",
      "message": "Cannot sort by field 'gXCroupState'.",
      "name": "FIELD_NOT_SORTABLE_EXCEPTION",
      "property": null,
      "parameters": {
        "%fieldName%": "groupStateXX"
      }
    }
  ]
}

← Best Practice →