Query Params

These features are available when getting all model data (only include, can be used on find). By default, you don't need to implement these features, just use them.

Model example

interface Post{
   id: number;
   title: string; 
   content: string;
   rating: number; 
   updated_at:string
   created_at:string;    
   deleted_at:string; // when has SoftDelete
}

Include

Whenever the include parameter is passed, the requested type will be included in the response object.

GET api/v1/addresses?include=city

you can use chaining, in which case cities and states will be added, with another country object aligned.

include=city.state.country

More than one include can be combined using the comma (,) to separate

include=city.state.country,users

P.S: Remember that whenever the include is in the singular, it will be a simple object, when in the plural an array of objects will be passed.

Query Search

Example: ?q=a

They will make queries with the operator * like * in several columns of the entity, in the case above, it would generate the following query in sql:

select * from title like “%a%” OR content like “%a%”

Conditional query

Multiple

Example: ?title=my title&rating=3

Most of the time the names of the model attributes can be used as a conditional rule. (notice the AND here):

select * from title = “my title” AND rating = 3”

Single

Example: ?categoria_id=1

To filter the list by other related models, usually represented by model_id or models_ids, for example, to filter a list and models by category.

Remember that whenever the parameter in question is in the singular, you should receive only one id, and when in the plural you will receive an array of IDs.

select * from model where categoria_id = 3

Soft Delete

These features are available when your model has a soft delete column deleted_at.

With Trashed

Example: ?withTrashed=1

This option will get all your model registers with the deleted ones:

select * from model

Only Trashed

Example: ?onlyTrashed=1

This option will get your model deleted registers:

select * from model where deleted_at != null

PS: You cannot use both at the same time, use one by time.

Sort

Example: ?sort=-rating,created_at

Sorts the results. To use descending order we use the - sign in front of the attribute, and for ascending order, just remove the front sign. In addition, it is possible to use more than one sorting parameter by separating them with a comma.

select * from order by rating DESC, created_at ASC”

Filter by date

Example: ?date_column=created_at&date_start=2018-05-05&date_end=2019-05-05

Filters the data by date ranges, in this case, all the records from 05/05/2018 to 05/05/2019 using as a parameter a created_at column that represents the creation date.

You can also specify the time, valid formats: Y-m-d ou Y-m-d H:i ou Y-m-d H:i:s

Of these 3 parameters, the only one that is mandatory is date_column:

• When passing just date_start will bring records from this date forward;
• When passing only date_end will bring records less than or equal to the date.

select * from created_at >= "2018-05-05" AND created_at <= "2019-05-05”

Filter by value

Example: ?value_column=rating&value_min=2&value_max=4

In a similar way to the filter by date, it is first necessary to specify which column should be consulted through the value_column, and in the sequence, it informs the interval, in this case, all the records with a rating between 2 and 4. Valid formats: float, int

Of these 3 parameters, the only one that is mandatory is value_column:

• When passing only value_min will bring records greater or equal;
• When passing only value_max will bring records smaller or equal;

select * from rating >= 2 AND rating <= 4

Limit

Example: ?take=5

This parameter determines the maximum number of results you want for your search, in the case of the example I want 5 results. This parameter can be combined with the others to determine the number of results.

select * from limit 5

Paginate

Example: ?paginate=5&page=1

Configures the pagination of the results with the parameter paginate responsible for determining the number of results per page and page for determining the page in question that you want.

In the case of the example above, you should page every 5 results starting from page 1. The page parameter is optional.

In this case, the server's response will be slightly different to allow a paging object to be built, see:

Interface example

export interface Links {
    first: string;
    last: string;
    prev?: any;
    next: string;
}

export interface MetaLinks {
    url?: string;
    label: string;
    active: boolean;
}

export interface Meta {
    current_page: number;
    from: number;
    last_page: number;
    links: MetaLinks
    path: string;
    per_page: string;
    to: number;
    total: number;
}

export interface ResponsePaginate<T> {
    data: T[];
    links: Links;
    meta: Meta;
}

JSON example:

{
    "data": [...],
    "links": {
        "first": "http://laravel.test/api/v1/users?paginate=5&page=1",
        "last": "http://laravel.test/api/v1/users?paginate=5&page=2",
        "prev": null,
        "next": "http://laravel.test/api/v1/users?paginate=5&page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 2,
         "links": [
      {
        "url": null,
        "label": "« Previous",
        "active": false
      },
      {
        "url": "http:\/\/localhost:81\/api\/users?page=1",
        "label": "1",
        "active": true
      },
      {
        "url": "http:\/\/localhost:81\/api\/users?page=2",
        "label": "2",
        "active": false
      },
      {
        "url": "http:\/\/localhost:81\/api\/users?page=3",
        "label": "3",
        "active": false
      },
      {
        "url": "http:\/\/localhost:81\/api\/users?page=2",
        "label": "Next »",
        "active": false
      }
    ],
        "path": "http://laravel.test/api/v1/users",
        "per_page": "5",
        "to": 5,
        "total": 10
    }
}