Querying

Easily make API requests for get resources.

Introduction

This features allows you to filter, sort and include deferent relations based on a request. This means all your favorite methods and macros are still available. Query parameter names follow the JSON API specification as closely as possible.


Filters

To use filters in a request, you must include the appropriate query parameters in the URL of your HTTP GET request.

Filters are a powerful way to narrow down the results of an HTTP request based on specific criteria. They enable API clients to selectively retrieve data that interests them. Be sure to clearly document the filters supported by your API so that developers can use them effectively.

Don't forget to provide concrete examples of requests with filters in your API documentation to assist users in understanding how to use them correctly.

The syntax for filters

The syntax for filters typically follows a key-value structure, where the key represents the field you want to filter on, and the value represents the condition you want to apply.

Example : GET /articles?filter[title]=Lorem%20ipsum

In this example, we are filtering articles where the "title" field is equal to "Lorem ipsum."

Combining Filters

You can combine multiple filters in a single request to further refine the results.

curl -X https://api.molink.fr/v2/users?filter[first_name]=John&filter[last_name]=Doe

Exprime CONTAIN sql expresion :

curl -X https://api.molink.fr/v2/users?filter[matriculee]=John,Paul,Jean

Includes

The include parameters are used to specify which additional data should be included in the results of a request. These parameters are commonly used in RESTful APIs to allow clients to specify the relationships they want to include with the main resources.

To use the includes parameters in a request, you need to include these parameters in the URL of the HTTP GET request. The includes parameter allows you to specify the relationships you want to include in the response.

Syntax

The syntax for includes parameters typically depends on the convention used by the API. However, a common convention is to separate the names of relationships with commas.

Example : GET /articles?includes=author,comments

In this example, we are requesting to include the data related to authors and the comments associated with the articles in the response.

Nested relationship

curl -X https://api.molink.fr/v2/articles?includes=author.address

Using "include" parameters in conjunction with other query parameters

The includes parameters can be combined with other query parameters, such as filters and sorting, to further customize the results of the request.

Example : GET /articles?includes=comments&filter[published]=true&sort=-created_at

In this example, we are requesting to include the comments of published articles and to sort the results by creation date in descending order.


Sorts

Sorting parameters, also known as sort, are used to specify how the results of a request should be sorted. These parameters are typically included in HTTP GET requests for RESTful web APIs.

To use sorting in a request, you must include the appropriate sorting parameters in the URL of the HTTP GET request. Commonly used sorting parameters include:

  • sort: The fundamental parameter to specify the sorting.
  • order: To specify the sorting order (ascending or descending).

In this documentation, we will focus on the use of the sort parameter..

Syntaxe du paramètre sort

The syntax for sorting parameters is typically straightforward. You specify the field you want to sort on, followed by the sorting order (ascending or descending), separated by an enum like asc.

Example : GET /articles?sort=title

In this example, we are requesting to sort the articles in ascending order based on the "title" field.

Sorting a query based on a request :

By default, sorting is done in descending order, meaning from largest to smallest.


curl -X https://api.molink.fr/v2/users?sort=created_at

Choose if sorting is descendant :

The sorting order can be specified by adding the `desc suffix after the field for descending sorting (from highest to lowest).

curl -X https://api.molink.fr/v2/users?sort=created_at.desc

Choose if sorting is ascendant

That's correct. The sorting order can be specified by adding the `desc suffix after the field for descending sorting (from highest to lowest).

curl -X https://api.molink.fr/v2/users?sort=created_at.asc`

Multi sort

You can also sort by multiple fields by separating them with commas in the sort parameter.

Example : GET /products?sort=category,price.asc

In this example, the products are sorted by category in ascending order, and then by price in descending order.