Skip to content

About

Monkey API Query Search By Specification

Resources

Stars

3 stars

Watchers

15 watching

Forks

Latest commit

 

History

81 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

monkey-specification-search

Monkey API Query Search By Specification

This project was created to help everyone to create a searchable Rest API :)

Operations:

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.

How to use:

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']

Required keys

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

CustomSpecificationSearch

With CustomSpecificationSearch, you can execute specifications using a request parameter. Follow the steps below to use it:

1. Create a Custom Specification

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)
        );
    };
}

2. Add a @Configuration Class to Your Project

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());
	}

}

3. Call the API Using the Custom Predicate

You can now call your API using the customPredicate as a search parameter. For example:

GET: host/v2/products?search=customPredicate:readyToUse

About

Monkey API Query Search By Specification

Resources

Stars

3 stars

Watchers

15 watching

Forks

Releases

Packages

Used by

Contributors

Languages