Query parameters

Query parameters are predefined parameters attached to a URL’s end. They define specific content or actions based on passed data. To append query parameters, use ?. To add multiple parameters, use &.

Example:

https://api.wpp.net/v1/orders?name=Branch&products=[Labels,Returns]

Purpose

• Limit the number of results or fields returned.
• Sort the returned results.

Expected behavior

• Query parameters are optional.
• Use lowercase and - to separate words (e.g., order-id).
• If a parameter is incorrect or unimplemented, it is ignored.
• Multiple parameters are treated as a logical AND.
• Escaped comma-separated values are treated as OR.
• If no records are found, the API returns 200 OK with an empty array.
• Incorrect values can result in 400 BAD REQUEST.

Filtering, paging, limit, etc.

APIs that support filtering, paging, or other operations should use these query parameters. All are optional and must be documented in the OpenAPI specification.

Parameter	Type	Description
search	string	Search multiple fields. Describe if it’s startsWith, endsWith, contains, or allows wildcards (*). Define the fields the search applies to.
limit	integer	Defines the number of instances returned per page. Must be >0. Example: /resource-api?limit=20.
offset	integer	Defines the starting position in the results. Default is 0. Example: /resource-api?limit=10&offset=40.
fields	string	Select specific fields. Example: fields=orderNumber,orderDate,orderLines(lineNumber,articleNumber),customAttributes(color,favoriteSeason).
sort	string	Sort fields by name. Example: /customers?sort=firstName,lastName,-age (orders by firstName, then lastName ascending, and age descending).

Logical expressions in query parameters

If supported, logical expressions help refine search queries.

Expression	Example	Description
gt	/customers?chdttm-gt=2020-07-22	Returns customers where chdttm > 2020-07-22.
gte	/customers?chdttm-gte=2020-07-22	Returns customers where chdttm ≥ 2020-07-22.
lt	/customers?chdttm-lt=2020-07-22	Returns customers where chdttm < 2020-07-22.
lte	/customers?chdttm-lte=2020-07-22	Returns customers where chdttm ≤ 2020-07-22.

Field selection

When an API has many fields and performance is affected, field selection can optimise queries.

Example:

/orders?fields=orderNumber,orderDate,orderLines(lineNumber,articleNumber),customAttributes(color,favoriteSeason)

Example response:

{
  "data": [
    {
      "orderId": "123-456",
      "orderDate": "date value",
      "orderLines": [
        {
          "lineNumber": 1,
          "articleNumber": "Art123"
        },
        {
          "lineNumber": 2,
          "articleNumber": "Art456"
        }
      ],
      "customAttributes": {
        "color": "yellow",
        "favoriteSeason": "summer"
      }
    }
  ]
}