Web API includes filters to add extra logic before or after an action method is executed. Filters provide cross-cutting features such as logging, exception handling, performance measurement.
Filters are actually attributes that can be applied on the Web API controller or on one or more action methods.
Following are filters allowed by BQE Core API:
- Fields - Specifies the model properties you want in the response body
- Where - Fetches records that match the query
- OrderBy - Organizes results in ascending or descending order, by a specified field
- Page - Determines the page number and total number of records on each page
- Expand - Allows nested or additional resources in the response body
- Count - Allows you to specify the total number of records
OrderBy can be used only with properties that have the Sortable attribute and Where can be used only with properties that have the Filterable attribute.
Use the fields parameter to specify only those model properties which you want in the response body. To return the complete model use (*) in the fields parameter. Multiple model properties are separated by a comma.
Example: An API call to the activity endpoint with id, name and description in the fields parameter.
In case of large sets, use the Record Count in the query to specify the total number of records. To return the total number of records in the response, use COUNT (*) in the fields parameter. Remember you cannot use OrderBy and Page when using Count. An API call to count the total number of activities in a project.
Use the where filter to specify only those records that match the query expression. You can use multiple filters in a single query to streamline your results. However, long and complex where queries can cause time outs. We recommend you keep them as simple as possible.
When passing enums that are filterable using the where clause, make sure you pass the values of the enums and not their descriptions.
In case of dates, we support ISO 8601 date time format, such as YYYY-MM-DDThh:mm:ss.
Example: An API call that lists only those activities, whose isActive status is true.
Example Enum: An API call that lists only those accounts that have the AccountType = 2 [Bank Account]
Example for Date: An API call that lists only those time entries whose date is greater than or equal to "2019-06-29" and less than or equal to "2019-07-30"
Use the orderby filter to specify by which field you want to order the item list. For example, you could choose to order a list of activities in a certain order. By default, results are listed in ascending order. You can change from ascending to descending order (and vice vsersa) using the asc and desc keywords.
Use the syntax shown in the following examples to retrieve the results in the order you want.
Example: This query returns the entire list of activities, sorted in ascending order by activity name
You can also use the ‘desc’ keyword to specify that the results are returned in descending order.Example: This query will return the same result as the above query, but in the descending order.
Use this filter to define the page number and number of records on each page. Sometimes, it can be difficult to screen through all the records displayed on a single page. The page filter comprises of number representing the page number and size representing the number of records.
- By default, twenty-five records are returned per page . if expand parameter is not used, a maximum of 1000 records can be returned.
- When using the expand parameter, you are only allowed to return a maximum of 100 records
- When requesting page 0, the first page is returned.
- When requesting a non-positive integer [-1,-2, -3, etc.], the first page is returned.
- When requesting a page beyond the last calculated page, a NULL result is returned marking the end of the result set.
Use the expand parameter to request for the nested or additional resources in your response object. By default, Core API only allows flat models in the response body. You can ask for multiple nested resources separated by a comma (,).Example: An API call to the employee endpoint requesting for custom fields.
An operator manipulates individual data items and returns a result. The data items are called operands or arguments. Operators are represented by special characters or keywords. For example, the equality operator is represented by an equal to sign (=) and the operator that tests for null value is represented by the keywords IS NULL. Core API allows the following classes of operators:
A comparison (or relational) operator is a mathematical symbol which is used to compare two values. Comparison operators are used in conditions that compares one expression with another.
|=||The equal to operator is used for equality test within two numbers or expressions|
|!=,<>||The not equal to operator is used for inequality test between two numbers or expression.|
|>||The greater than operator is used to test whether an expression (or number) is greater than another one.|
|<||The less than operator is used to test whether an expression (or number) is less than another one.|
|>=||The greater than equal to operator is used to test whether an expression (or number) is either greater than or equal to another one.|
|<=||The less than equal to operator is used to test whether an expression (or number) is either less than or equal to another one.|
|IN||The IN operator checks a value within a set of values separated by commas and retrieve the results which are matching|
|NOT IN||The NOT IN operator is used to exclude the defined multiple value in a WHERE clause condition.|
|BETWEEN||The BETWEEN operator tests an expression against a range. The range consists of a beginning, followed by an AND keyword and an end expression|
|LIKE||The LIKE operator determines if a character string matches a specified pattern. A pattern may include regular characters and wildcard characters. The LIKE operator is used in the WHERE clause of the SELECT, UPDATE, and DELETE statements to filter rows based on pattern matching.|
|NOT LIKE||The NOT LIKE is used to exclude those rows which are matching the criterion followed by LIKE operator.|
You should URL encode the where clause in the query parameter where-ever possible.
The logical operators are those that are true or false. They return true or false values to combine one or more true or false values.
|AND||Logical AND compares between two Booleans as expression and returns true when both expressions are true|
|OR||Logical OR compares between two Booleans as expression and returns true when one of the expression is true|