Skip to content

API Documentation

Jump to bottom
Alexis Pavlidis edited this page Sep 7, 2019 · 4 revisions

Contents

Notes

Supported Projects

The project currently supports the Queries only to a MongoDB database.

Contribute

If you find any error or any malfunction on the library please report it, or make a pull request to fix it.

Queries

The supported supported queries are: Sort, Select, Filter, Pagination.

Sort

In order to specify sorting to the database you have to add the parameter sort with value the name of your field of your entity.
For example defining a parameter sort=firstName on your url, will sort the results based on the firstName field with ascending order.

You can define a descending order by adding the - symbol in front of your field.
For example defining a parameter sort=-date on your url, will sort the results based on the date field with descending order.

Select

In order to specify specific fields to be returned you have to add the parameter select with value the names of your fields of your entity.
For example defining a parameter select=username,lastName,firstName on your url, will only fetch the fields username, lastName, firstName.

Note: Remaining fields will be returned with null value.

Pagination

In order to limit the results of your query you have to add the parameter pageSize with value a number between greater than or equal to 0.For example defining a parameter pageSize=1 on your url, will only fetch one document of your result set.

You can specify the page of your result set by adding the parameter page with value a number between greater than or equal to 0.
For example defining a parameter page=0 on your url and a pageSize=2, will fetch the first page of two documents.
If you don't specify the limit of results then a subset will be returned depending of the value of the page parameter. Here are some examples:

  • Defining a parameter page=0 on your url without a pageSize, will fetch all the results.
  • Defining a parameter page=1 on your url without a pageSize, will fetch all the results except the first document.
  • Defining a parameter page=2 on your url without a pageSize, will fetch all the results except the first two documents.

Filter

In order to query your results you have to add the parameter q with value a json object.
For example defining a parameter q={"age":"18"} on your url, will only fetch the documents that fulfill that query, in our case the age has to be equal to 18.

Exceptions

Defining wrong query parameters will throw a WrongQueryParam with a human readable message to specify the type of the error.

Examples

Filtering

Lets say you want to filter the results by searching the text that contains the string "123".

GET /example?q={"text":"123"}

Lets say you want to filter the results by searching the text that contains the string "123" and the title that contains the string "hello"

GET /example?q={"text":"123","title":"hello"}

Sorting

Let's say you want to order the results by ordering the title descending.

GET /example?sort=-title

Let's say you want to order the results by ordering the title ascending.

GET /example?sort=title

Pagination

Let's say you want to limit the results by 5 entries.

GET /example?pageSize=5

Let's say you want the next page of the results after limiting it by 5 entries.

GET /example?pageSize=5&page=2

Selecting

Here you retrieve specifically only the title and the text of the results' objects

GET /example?select=title,text

All together

Here you retrieve only the objects that have the string "123" in the text field. For those objects, only the fields "title" and "text" is returned sorted by title descending. The results are limited by 5 entries and you only retrieve the second page.

GET /example?select=title,text&q={"text":"123"}&pageSize=5&page=2&sort=title

Clone this wiki locally