Spring – Add New Query Parameters in GET Call Through Configurations

When a client wants to adopt the API sometimes the existing query parameters may not be sufficient to get the resources from the data store. New clients can’t onboard until the API providers add support for new query parameter changes to the production environment. To address this problem below is a possible solution to support new query parameters on the fly. With this design supporting new query parameters will be as easy as adding new query parameters as property in the applications configuration file. Implemented this using Spring Boot framework and MongoDB as the backend database.

HTTP GET is two types, path parameters, and query parameters. In this article, we are discussing query parameters. Query parameter GET call is a set of parameters that are part of the url. Query parameters are appended in the url after the HTTP resource with the ‘?’ symbol and multiple parameters are concatenated by & symbol. Here is an example: 

http://localhost:8080/orders?invoiceNumber=387373872&items.forPerson.resourceId=9714a305-a9ec-4a3f-9ba6–93766b2c77b7

Implementation

The important part of this design is supporting the query parameters as they are referred to in the JSON path. With this, we can simply include the JSON path as the key and values in the Mongo Query. From the below JSON example, forPerson resourceId for JSON path is items.forPerson.resourceId.

{
    "_id": UUID('92f4b597-467a-4094-b796-27d1124c2fbd'),
    "forName": {
           "firstName": "Hemanth",
           "lastName": "Atluri"
          },
    "invoiceNumber": "387373872",
    "items":[
          "resourceId": UUID('bad40e6b-4d17-433c-9c56-b61ea5bef06f'),
      "forPerson": {
        "resourceId": "9714a305-a9ec-4a3f-9ba6–93766b2c77b7"
          }
     ] 
}

In the implementation, all the query parameters provided are applied in AND fashion to filter the resources. Some of the query parameters have to be supported with exact values, greater than this value, and less than this value if this element exists. To support this, I used keywords from, to, after, before, and exists and added these to request parameters with the delimiter. Below is an example:

http://localhost:8080/orders?invoiceNumber=387373872&items.forPerson.resourceId=9714a305-a9ec-4a3f-9ba6–93766b2c77b7&orderDate:from=08/13/2022&orderDate:to=10/13/2022

Now let’s see the code to get a better understanding. Let’s start with the Controller code: Controller class takes the help of RequestParamValidatorAndConvertor and MongoHelper to give a response back to the client. The core logic is in these two classes. Below is the code snippet:

Java

@RestController
@RequestMapping("/v1/orders")
public class MongoRestController {

    Logger log = LoggerFactory.getLogger(MongoRestController.class);

    @Autowired
    private RequestParamValidatorAndConvertor requestParamValidatorAndConvertor;

    @Autowired
    private MongoHelper mongoHelper;

    @GetMapping
    public ResponseEntity search(@RequestParam MultiValueMap<String, String> requestParams) {
        ResponseEntity responseEntity = null;
        try {
            List<QueryParameter> queryParameters = requestParamValidatorAndConvertor.validateAndConvertToQueryParameters(requestParams);
            List<Order> orders = mongoHelper.getOrders(queryParameters);
            responseEntity = ResponseEntity.status(HttpStatus.OK).body(orders);
        } catch (IllegalArgumentException ex) {
            responseEntity = ResponseEntity.status(HttpStatus.BAD_REQUEST).body("UnSupported Query Parameter");
        }
        return responseEntity;
    }
}

In the RequestParamValidatorAndConvertor validates the provided query parameter and converts them into a List of CustomCriteria.Below is the code snippet:

Java

public enum MongoOperator {
    IN, EXISTS, LT,LTE,GT,GTE;
}

Java

@NoArgsConstructor
@AllArgsConstructor
@Data
public class QueryParameter {
    private String attributeName;
    private String value;
    private MongoOperator mongoOperator;
}

Java

@Component
public class RequestParamValidatorAndConvertor {

    @Value("#{'${supportedQueryParamters}'.split(',')}")
    private List<String> supportedQueryParamters;

    public List<QueryParameter> validateAndConvertToQueryParameters(MultiValueMap<String, String> requestParams) {
        List<QueryParameter> queryParameters = new ArrayList<>();

        requestParams.forEach((key, value) -> {
            QueryParameter qp = new QueryParameter();
            if (key.contains(":")) {
                String[] keySplits = key.split(":");
                MongoOperator mongoOperator = null;

                String queryParameter = keySplits[0];
                String queryParamOperator = keySplits[1];

                if (!supportedQueryParamters.contains(queryParameter)) {
                    throw new IllegalArgumentException("Unsupported Query Parameter");
                }
                if (queryParamOperator.endsWith("from")) {
                    mongoOperator = MongoOperator.GTE;
                }
                if (queryParamOperator.endsWith("to")) {
                    mongoOperator = MongoOperator.LTE;
                }
                if (queryParamOperator.endsWith("after")) {
                    mongoOperator = MongoOperator.GT;
                }
                if (queryParamOperator.endsWith("before")) {
                    mongoOperator = MongoOperator.LT;
                }
                if (queryParamOperator.endsWith("exists")) {
                    mongoOperator = MongoOperator.EXISTS;
                }

                qp.setAttributeName(queryParameter);
                qp.setMongoOperator(mongoOperator);

            } else {
                if (!supportedQueryParamters.contains(key)) {
                    throw new IllegalArgumentException("Unsupported Query Parameter");
                }
                qp.setAttributeName(key);
                qp.setMongoOperator(MongoOperator.IN);
            }

            qp.setValue(String.valueOf(value));
            queryParameters.add(qp);
        });
        return queryParameters;
    }
}

MongoHelper class encapsulates building the criteria and querying the MongoDB. Below is the code snippet:

Java

@Component
@AllArgsConstructor
public class MongoHelper {

    private MongoCriteriaBuilder mongoCriteriaBuilder;
    private MongoCustomRepository mongoCustomRepository;

    public List<Order> getOrders(List<QueryParameter> queryParameters) {
        Criteria criteria = mongoCriteriaBuilder.build(queryParameters);
        return mongoCustomRepository.findOrders(criteria);
    }
}

MongoCriteriaBuilder takes the QueryParameters for each query parameter it creates Criteria and chains individual criteria with the AND operator.

Java

@Component
public class MongoCriteriaBuilder {

    public Criteria build(List<QueryParameter> queryParameters) {
        List<Criteria> criterias = new ArrayList<>();
        queryParameters.forEach(queryParameter -> {
            Criteria criteria = null;
            switch (queryParameter.getMongoOperator()) {
                case EXISTS:
                    criteria = Criteria.where(queryParameter.getAttributeName()).exists(Boolean.getBoolean(queryParameter.getValue()));
                case GT:
                    criteria = Criteria.where(queryParameter.getAttributeName()).gt(queryParameter.getValue());
                case GTE:
                    criteria = Criteria.where(queryParameter.getAttributeName()).gte(queryParameter.getValue());
                case LT:
                    criteria = Criteria.where(queryParameter.getAttributeName()).lt(queryParameter.getValue());
                case LTE:
                    criteria = Criteria.where(queryParameter.getAttributeName()).lte(queryParameter.getValue());
                default:
                    List<String> values = Arrays.stream(queryParameter.getValue().split(",")).collect(Collectors.toList());
                    criteria = Criteria.where(queryParameter.getAttributeName()).in(values);
            }
            criterias.add(criteria);
        });
        Criteria criteria = new Criteria().andOperator(criterias.toArray(new Criteria[criterias.size()]));
        return criteria;
    }
}

MongoCustomRepository builds the mongo query with the criteria from the MongoCriteriaBuilder and passes it to the MongoTemplate to get the List of documents back.

Java

@Component
@AllArgsConstructor
public class MongoCustomRepository {

    private MongoTemplate mongoTemplate;

    public List<Order> findOrders(Criteria criteria){
        Query query = new Query();
        query.addCriteria(criteria);
        return mongoTemplate.find(query, Order.class);
    }
}

Conclusion

With the above implementation, new query parameters can be supported through configurations. This article talks about querying, but this doesn’t include the performance of the query. To achieve performance in the query one must index the field and understand the MongoDB indexing.