Skip to main content

IPA-129: Query Parameters

Query parameters can be appended to the request URI and are useful for providing optional parameter values in the request. These values can be used for filtering, sorting, searching and pagination. Query parameters can help clients retrieve only the items they are interested in, or format the response in a specified way.

State

Experimental

Guidance​

  • API Producers may use query parameters for:
  • Query parameters must not be used in place of request body fields for Create and Update Methods, i.e. when the value causes a side-effect
  • Query parameters must not be required
  • API Producers should document the possible length of query parameter values
    • For string query parameters, API Producers should document the maximum allowed length of the value
  • The number of distinct query parameters for a method must not exceed 10
    • A high number of query parameters may lead to performance issues
    • Some browsers and servers may have limits for URI lengths

Formatting​

  • Query parameters must be provided in the URI. The query component starts with the first question mark (?) character and is terminated by the number sign (#) character, or by the end of the URI
  • Query parameters must be formatted as key-value pairs and separated with an ampersand (&)

Example:

/resource/{id}?name=peter&age=25

See IETF RFC3986 - 3.4.

Array Query Parameters​

Array query parameters are query parameters that accept a list of values.

  • Array query parameters must be provided by repeating the key and value of the parameter, for each value in the list
  • API Producers must document which query parameters accept array values
  • API Producers must document the maximum number of array items using the maxItems property
    • The maxItems property must not exceed 20
  • Empty arrays must be handled gracefully, i.e. not cause an error response

Example:

/resource/{id}?name=peter&name=linda&name=sam

Filtering & Searching​

Query parameters can be used to filter or search responses by specific field values.

Further Reading​