Monkey API Query Search By Specification
This project was created to help everyone to create a searchable Rest API :)
| Operator | Description | Example |
|---|---|---|
: |
Equal | invoiceKey:ABC123, seller.id:10 |
! |
Not equal | invoiceKey!ABC123, seller.id!10 |
> |
Greater than or equal to | paymentValue>200, seller.id>10, createdAt>2021-12-23 |
< |
Less than or equal to | paymentValue<200, seller.id<10, createdAt<2021-12-23 |
:value* |
Starts with | invoiceNumber:AB*, seller.name:Feli* |
!value* |
Does not start with | invoiceNumber!AB*, seller.name!Feli* |
OR |
Logical OR | invoiceNumber:ABC123 OR seller.name:Felipe |
AND |
Logical AND | invoiceNumber:ABC123 AND seller.name:Felipe |
IN |
Value is in list | invoiceNumber IN ['123', '456'], seller.id IN [1, 2] |
() |
Parenthesis | seller.name:Felipe* OR (invoiceNumber:123 AND createdAt>2021-12-23) |
Prefix filters (:value* and !value*) are case-insensitive. Only a trailing * selects a prefix
operation; ends-with and contains filters are not supported by the current SearchCriteria mapping.
Add a search parameter on your URL like this:
?search=color:white AND car.field:foo AND car.field2!bar OR car.field3:200 OR car.field4 IN ['foo','bar']Use required to force the search to always contain some keys:
@GetMapping
PagedModel<EntityModel<InvoiceEntriesResponse>> findAll(
@SearchParameter(required = InvoiceEntries_.EXTERNAL_ID) Specification<InvoiceEntries> search,
Pageable pageable) {
...
}Any criterion on the key counts, whatever the operator (:, !, >, <, :value*, !value*, IN) or logical operation
(AND, OR, parenthesis). When a key is missing — or the search parameter is missing or empty — the resolver
throws a BadRequestException (Search parameter must filter by: <keys>).
Search (required = "externalId") |
Result |
|---|---|
externalId:1, externalId:1 AND seller.id:2 |
✅ |
externalId:1 OR seller.id:2, externalId!1 |
✅ |
externalId:1*, externalId IN ['1', '2'] |
✅ |
seller.id:2 |
❌ 400 |
no search parameter |
❌ 400 |
With CustomSpecificationSearch, you can execute specifications using a request parameter. Follow the steps below to use it:
Define a custom specification for your model. For example, to create a specification that checks if a product is in one of two specific states:
public static Specification<Product> readyToUse() {
return (root, criteriaQuery, criteriaBuilder) -> {
return criteriaBuilder.or(
criteriaBuilder.equal(root.get(Product_.status), ENUM_STATUS_1),
criteriaBuilder.equal(root.get(Product_.status), ENUM_STATUS_2)
);
};
}Create a class annotated with @Configuration to register the custom specification in CustomSpecificationSearch:
@Configuration
class MonkeySpecificationSearchConfiguration {
@PostConstruct
void customSpecification() {
CustomSpecificationSearch.getInstance().add("productReadyToUse", ProductSpecification.readyToUse());
}
}You can now call your API using the customPredicate as a search parameter. For example:
GET: host/v2/products?search=customPredicate:readyToUse