---
title: 'REST APIs'
position: 1010
category: 'Developer Resources'
menuTitle: 'REST APIs'
---

<announcement></announcement>

## Features

* **Automatic REST APIs for any SQL database** 
  * Generates REST APIs for **ANY** MySql, Postgres, MSSQL, Sqlite database
  * Serves APIs irrespective of naming conventions of primary keys, foreign keys, tables etc
  * Support for composite primary keys
  * REST APIs : 
      * CRUD, List, FindOne, Count, Exists, Distinct (Usual suspects)
          * Pagination 
          * Sorting
          * Column filtering - Fields
          * Row filtering - Where
      * Bulk insert, Bulk delete, Bulk read
      * Relations - automatically detected
      * Aggregate functions
  * More
      * Upload single file
      * Upload multiple files
      * Download file
  * Authentication
  * Access Control


## Data APIs

|  **Method**  |  **Path**  | **Query Params** | **Description**  |
|---|---|---|---|
|  **GET** | [/api/v1/tableName](#list)  | [where, limit, offset, sort, fields, mm, bt, hm](#query-params) | List rows of the table |
|  **POST** | [/api/v1/tableName](#create)  | | Insert row into table |
|  **PUT** | [/api/v1/tableName/:id](#update)  | | Update existing row in table |
|  **GET** | [/api/v1/tableName/:id](#get-by-primary-key)  | | Get row by primary key |
|  **GET** | [/api/v1/tableName/:id/exists](#exists)  | | Check row with provided primary key exists or not |
|  **DELETE** | [/api/v1/tableName/:id](#delete)  | | Delete existing row in table |
|  **GET** | [/api/v1/tableName/findOne](#find-one)  | [where, limit, offset, sort, fields](#query-params) | Find first row which matches the conditions in table |
|  **GET** | [/api/v1/tableName/groupby/:columnName](#group-by) | | Group by columns |
|  **GET** | [/api/v1/tableName/distribution/:columnName](#distribution) | |  Distribute data based on column |
|  **GET** | [/api/v1/tableName/distinct/:columnName](#distinct) | |  Find distinct column values |
|  **GET** | [/api/v1/tableName/aggregate/:columnName](#aggregate) | |  Do aggregation on columns |
|  **GET** | [/api/v1/tableName/count](#count) | [where](#query-params) |  Get total rows count |
|  **POST** | [/api/v1/tableName/bulk](#bulk-insert) |  |  Bulk row insert |
|  **PUT** | [/api/v1/tableName/bulk](#bulk-update) |  |  Bulk row update |
|  **DELETE** | [/api/v1/tableName/bulk](#bulk-delete) |  |  Bulk row delete |


<alert>
    <em>
        * <strong>tableName</strong> - Alias of the corresponding table <br>
        * <strong>columnName</strong> - Alias of the column in table
    </em>
</alert>

### Query params


|  **Name**    | **Alias** | **Use case** | **Default value**  |**Example value**  |
|---|---|---|---|---|
|  [where](#comparison-operators)  | [w](#comparison-operators)  |  Complicated where conditions | | `(colName,eq,colValue)~or(colName2,gt,colValue2)` <br />[Usage: Comparison operators](#comparison-operators) <br />[Usage: Logical operators](#logical-operators) |
|  limit  | l |  Number of rows to get(SQL limit value)  | 10  | 20 |
|  offset  | o |  Offset for pagination(SQL offset value)  | 0  | 20 |
|  sort  | s |  Sort by column name, Use `-` as prefix for descending sort  |   | column_name |
|  fields  | f |  Required column names in result  |  * | column_name1,column_name2 |
|  fields1  | f1 |  Required column names in child result  |  * | column_name1,column_name2 |
|  bt  |  |  Comma-separated belongs to tables  | `All belongs to tables` | [click here for example](#nested-parentbelongs-to) |
|  bfields`<p>`  | bf`<p>`  |  Required belongs to table column names in result. Where `<p>` refers to position of table name in `bt` parameter(starts from `1`)  | primary key and primary value | [click here for example](#nested-parentbelongs-to) |
|  hm  |  |  Comma-separated has many tables  | `All hasmany tables` | [click here for example](#nested-childrenhas-many) |
|  hfields`<p>`  | hf`<p>`  |  Required has many table column names in result. Where `<p>` refers to position of table name in `hm` parameter(starts from `1`) | primary key and primary value | [click here for example](#nested-childrenhas-many) |
|  mm  |  |  Comma-separated many to many tables  | `All many to many tables` | [click here for example](#nested-childrenmany-to-many) |
|  mfields`<p>`  | mf`<p>`  |  Required many to many table column names in result. Where `<p>` refers to position of table name in `mm` parameter(starts from `1`) | primary key and primary value | [click here for example](#nested-childrenmany-to-many) |


## HasMany APIs

|  **Method**  |  **Path**  | **Query Params** | **Description**  |
|---|---|---|---|
|  **GET** | [/api/v1/tableName/has/childTableName](#with-children)  | [where, limit, offset, sort, fields, fields1](#query-params) | List rows of the table with children |
|  **GET** | [/api/v1/tableName/:parentId/childTableName](#children-of-parent)  | [where, limit, offset, sort, fields, fields1](#query-params) | Get children under a certain parent |
|  **POST** | [/api/v1/tableName/:parentId/childTableName](#insert-to-child-table)  |  | Insert children under a certain parent |
|  **GET** | [/api/v1/tableName/:parentId/childTableName/findOne](#findone-under-parent)  | where, limit, offset, sort, fields | Find children under a parent with conditions |
|  **GET** | [/api/v1/tableName/:parentId/childTableName/count](#child-count)  |  | Find children count |
|  **GET** | [/api/v1/tableName/:parentId/childTableName/:id](#get-child-by-primary-key)  |  | Find child by id |
|  **PUT** | [/api/v1/tableName/:parentId/childTableName/:id](#update-child-by-primary-key)  |  | Update child by id |

<alert>
    <em>
        * <strong>tableName</strong> - Name of the parent table <br>
        * <strong>parentId</strong> - Id in parent table <br>
        * <strong>childTableName</strong> - Name of the child table
        * <strong>id</strong> - Id in child table
    </em>
</alert>

## BelongsTo APIs

|  **Method**  |  **Path**  | **Query Params** | **Description**  |
|---|---|---|---|
|  **GET** | [/api/v1/childTableName/belongs/parentTablename](#with-parent)  | where, limit, offset, sort, fields | List rows of the table with parent |


<alert>
    <em>
        * <strong>tableName</strong> - Name of the parent table <br>
        * <strong>childTableName</strong> - Name of the child table
    </em>
</alert>


#### Comparison operators

```
eq      -   '='         -  (colName,eq,colValue)
not     -   '!='        -  (colName,not,colValue)
gt      -   '>'         -  (colName,gt,colValue)
ge      -   '>='        -  (colName,ge,colValue)
lt      -   '<'         -  (colName,lt,colValue)
le      -   '<='        -  (colName,le,colValue)
is      -   'is'        -  (colName,is,true/false/null)
isnot   -   'is not'    -  (colName,isnot,true/false/null)
in      -   'in'        -  (colName,in,val1,val2,val3,val4)
btw     -   'between'   -  (colName,btw,val1,val2) 
nbtw    -  'not between'-  (colName,nbtw,val1,val2) 
like    -   'like'      -  (colName,like,%name)
```

#### Example use of comparison operators - complex example
```
/api/payments?where=(checkNumber,eq,JM555205)~or((amount,gt,200)~and(amount,lt,2000))
```

#### Logical operators
```
~or     -   'or'
~and    -   'and'
~not    -   'not'
```


## Examples

### List


<code-group>
  <code-block label="Request" active> 
  
  ```text
  GET /api/v1/country
  ```
  
  </code-block>
  <code-block label="Response">
  
  ```json
[
    {
        "country_id": 1,
        "country": "Afghanistan",
        "last_update": "2006-02-14T23:14:00.000Z"
    }
]
  ```
  </code-block>
</code-group> 



### List + where

<code-group>
  <code-block label="Request" active> 
  
  ```text
  GET /api/v1/country?where=(country,like,United%)
  ```

  </code-block>
    <code-block label="Response">
  
  ```json
[
    {
        "country_id": 101,
        "country": "United Arab Emirates",
        "last_update": "2006-02-15T04:44:00.000Z"
    },
    {
        "country_id": 102,
        "country": "United Kingdom",
        "last_update": "2006-02-15T04:44:00.000Z"
    },
    {
        "country_id": 103,
        "country": "United States",
        "last_update": "2006-02-15T04:44:00.000Z"
    }
]
  ```
  </code-block>
</code-group> 
<em><a href="#comparison-operators">Usage : comparison operators</a></em>

#### List + where + sort

<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/country?where=(country,like,United%)&sort=-country
```

</code-block>
<code-block label="Response"> 

```
[
    {
        country_id: 103,
        country: "United States",
        last_update: "2006-02-15T04:44:00.000Z"
    },
    {
        country_id: 102,
        country: "United Kingdom",
        last_update: "2006-02-15T04:44:00.000Z"
    },
    {
        country_id: 101,
        country: "United Arab Emirates",
        last_update: "2006-02-15T04:44:00.000Z"
    }
]
```
    
  </code-block>
</code-group>


### List + where + sort + offset

<code-group>
  <code-block label="Request" active> 
  
``` 
GET  /api/v1/country?where=(country,like,United%)&sort=-country&offset=1
```

</code-block>
<code-block label="Response"> 

```json
[
    {
        country_id: 102,
        country: "United Kingdom",
        last_update: "2006-02-15T04:44:00.000Z"
    },
    {
        country_id: 101,
        country: "United Arab Emirates",
        last_update: "2006-02-15T04:44:00.000Z"
    }
]
```
  </code-block>
</code-group>


### List + limit


<code-group>
  <code-block label="Request" active> 
  
``` 
GET  /api/v1/country?limit=6
```

</code-block>
<code-block label="Response"> 

```json
[
    {
        "country_id": 1,
        "country": "Afghanistan",
        "last_update": "2006-02-14T23:14:00.000Z"
    },
    {
        "country_id": 2,
        "country": "Algeria",
        "last_update": "2006-02-14T23:14:00.000Z"
    },
    {
        "country_id": 3,
        "country": "American Samoa",
        "last_update": "2006-02-14T23:14:00.000Z"
    },
    {
        "country_id": 4,
        "country": "Angola",
        "last_update": "2006-02-14T23:14:00.000Z"
    },
    {
        "country_id": 5,
        "country": "Anguilla",
        "last_update": "2006-02-14T23:14:00.000Z"
    },
    {
        "country_id": 6,
        "country": "Argentina",
        "last_update": "2006-02-14T23:14:00.000Z"
    }
]
```
  </code-block>
</code-group>
    
[⤴️](#api-overview)

  
### Get By Primary Key


<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/country/1
```


</code-block>
<code-block label="Response"> 

```json
{
    "country_id": 1,
    "country": "Afghanistan",
    "last_update": "2006-02-14T23:14:00.000Z"
}
```
  </code-block>
</code-group>

[⤴️](#api-overview)


### Create


<code-group>
  <code-block label="Request" active> 
  
```
POST  /api/v1/country
```

```json
{
    "country": "Afghanistan"
}
```


</code-block>
<code-block label="Response"> 

```json
{
    "country_id": 1,
    "country": "Afghanistan",
    "last_update": "2006-02-14T23:14:00.000Z"
}
```

  </code-block>
</code-group>

[⤴️](#api-overview)


### Update

<code-group>
  <code-block label="Request" active> 
  
```
PUT  /api/v1/country/1
```

```
{
    "country": "Afghanistan1"
}
```

</code-block>
<code-block label="Response">

```json
{
    "country_id": 1,
    "country": "Afghanistan1",
    "last_update": "20020-02-14T23:14:00.000Z"
}
```
  </code-block>
</code-group>

[⤴️](#api-overview)


### Exists

<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/country/1/exists
```

</code-block>
<code-block label="Response"> 

```json
true
```
  </code-block>
</code-group>

[⤴️](#api-overview)


### Delete


<code-group>
  <code-block label="Request" active> 
  
```
DELETE  /api/v1/country/1
```

</code-block>
<code-block label="Response"> 

```json
1
```
  </code-block>
</code-group>



[⤴️](#api-overview)

  
### Find One

<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/country/findOne?where=(country_id,eq,1)
```

</code-block>
<code-block label="Response"> 

```json
{
    "country_id": 1,
    "country": "Afghanistan",
    "last_update": "2006-02-14T23:14:00.000Z"
}
```
  </code-block>
</code-group>

[⤴️](#api-overview)

  
### Group By

<code-group>
  <code-block label="Request" active> 
    
```
GET  /api/v1/country/groupby/last_update
```

</code-block>
<code-block label="Response">
 
```json
[
    {
        "count": 109,
        "last_update": "2006-02-14T23:14:00.000Z"
    },
    {
        "count": 1,
        "last_update": "2020-01-06T15:18:13.000Z"
    },
    {
        "count": 1,
        "last_update": "2020-01-06T14:33:21.000Z"
    }
]
 ``` 
  </code-block>
</code-group>  

[⤴️](#api-overview)

  
### Distribution

<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/payment/distribution/amount
```

</code-block>
<code-block label="Response"> 

```json
[
    {
        "count": 8302,
        "range": "0-4"
    },
    {
        "count": 3100,
        "range": "5-8"
    },
    {
        "count": 371,
        "range": "9-11.99"
    }
]
```
  </code-block>
</code-group>

[⤴️](#api-overview)

  
### Distinct

<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/country/distinct/last_update
```

</code-block>
<code-block label="Response"> 

```json
[
    {
        "last_update": "2006-02-14T23:14:00.000Z"
    },
    {
        "last_update": "2020-01-06T15:18:13.000Z"
    },
    {
        "last_update": "2020-01-06T14:33:21.000Z"
    },
    {
        "last_update": "2020-01-07T13:42:01.000Z"
    }
]
```
  </code-block>
</code-group>

[⤴️](#api-overview)

  
### Aggregate

<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/payment/aggregate/amount?func=min,max,avg,sum,count
```

</code-block>
<code-block label="Response"> 

```json
[
    {
        "min": 0,
        "max": 11.99,
        "avg": 4.200743,
        "sum": 67413.52,
        "count": 16048
    }
]
```
  </code-block>
</code-group>

[⤴️](#api-overview)

  
### Count

<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/country/count
```

</code-block>
<code-block label="Response"> 

```json
{
    "count": 161
}
```
  </code-block>
</code-group>

[⤴️](#api-overview)  




### Nested Parent(Belongs To)

<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/City?bt=country&bfields1=Country,CountryId
```

</code-block>
<code-block label="Response"> 

```json
[
  {
    "CityId": 1,
    "City": "A Corua (La Corua)",
    "CountryId": 87,
    "LastUpdate": "2006-02-14T23:15:25.000Z",
    "CountryRead": {
      "CountryId": 87,
      "Country": "Spain"
    }
  },
  {
    "CityId": 2,
    "City": "Abha",
    "CountryId": 82,
    "LastUpdate": "2006-02-14T23:15:25.000Z",
    "CountryRead": {
      "CountryId": 82,
      "Country": "Saudi Arabia"
    }
  },
  {
    "CityId": 3,
    "City": "Abu Dhabi",
    "CountryId": 101,
    "LastUpdate": "2006-02-14T23:15:25.000Z",
    "CountryRead": {
      "CountryId": 101,
      "Country": "United Arab Emirates"
    }
  }
]
```
  </code-block>
</code-group>

[⤴️](#api-overview)

### Nested Children(Has Many)

<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/Country?hm=city&hfields1=City,CityId
```

</code-block>
<code-block label="Response"> 

```json
[
  {
    "CountryId": 1,
    "Country": "Afghanistan",
    "LastUpdate": "2021-11-15T14:11:37.000Z",
    "CityList": [
      {
        "CityId": 251,
        "City": "Kabul",
        "CountryId": 1
      }
    ]
  },
  {
    "CountryId": 2,
    "Country": "Algeria",
    "LastUpdate": "2021-11-15T14:11:42.000Z",
    "CityList": [
      {
        "CityId": 59,
        "City": "Batna",
        "CountryId": 2
      },
      {
        "CityId": 63,
        "City": "Bchar",
        "CountryId": 2
      },
      {
        "CityId": 483,
        "City": "Skikda",
        "CountryId": 2
      }
    ]
  },
  {
    "CountryId": 3,
    "Country": "American Samoa",
    "LastUpdate": "2006-02-14T23:14:00.000Z",
    "CityList": [
      {
        "CityId": 516,
        "City": "Tafuna",
        "CountryId": 3
      }
    ]
  }
]
```
  </code-block>
</code-group>

[⤴️](#api-overview)



### Nested Children(Many To Many)

<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/Actor?l=3&mm=film&mfields1=ReleaseYear
```

</code-block>
<code-block label="Response"> 

```json
[
  {
    "ActorId": 1,
    "FirstName": "PENELOPE",
    "LastName": "GUINESS",
    "LastUpdate": "2021-11-24T14:43:23.000Z",
    "FilmMMList": [
      {
        "actor_actor_id": 1,
        "FilmId": 1,
        "Title": "Test Movie 1",
        "ReleaseYear": 2001
      }
    ]
  },
  {
    "ActorId": 2,
    "FirstName": "NICK",
    "LastName": "WAHLBERG",
    "LastUpdate": "2006-02-14T23:04:33.000Z",
    "FilmMMList": [
      {
        "actor_actor_id": 2,
        "FilmId": 1,
        "Title": "Test Movie 2",
        "ReleaseYear": 2002
      }
    ]
  },
  {
    "ActorId": 3,
    "FirstName": "ED",
    "LastName": "CHASE",
    "LastUpdate": "2006-02-14T23:04:33.000Z",
    "FilmMMList": [
      {
        "actor_actor_id": 3,
        "FilmId": 1,
        "Title": "Test Movie 3",
        "ReleaseYear": 2000
      }
    ]
  }
]
```
  </code-block>
</code-group>

[⤴️](#api-overview)



















  
### Bulk Insert

<code-group>
  <code-block label="Request" active> 
  
```
POST  /api/v1/country/bulk
```

```json
[
    {
        "country": "test 1"
    },
    {
        "country": "test 2"
    }
]
```

</code-block>
<code-block label="Response"> 

```json
[
    10262
]
```
  </code-block>
</code-group>

[⤴️](#api-overview)

  
### Bulk Update
<code-group>
  <code-block label="Request" active> 
  
```
PUT  /api/v1/country/bulk
```

```json
[
    {
        "country_id" : 10261,
        "country": "test 3"
    },
    {
        "country_id" : 10262,
        "country": "test 4"
    }
]
```
</code-block>
<code-block label="Response"> 

```json
[
    1,
    1
]
```
  </code-block>
</code-group>

[⤴️](#api-overview)

  
### Bulk Delete

<code-group>
  <code-block label="Request" active> 
  
```
DELETE  /api/v1/country/bulk
```

```json
[
    {
        "country_id" : 10261
    },
    {
        "country_id" : 10262
    }
]
```
</code-block>
<code-block label="Response"> 

```json
[
    1,
    1
]
```
  </code-block>
</code-group>

[⤴️](#api-overview)

  
### With Children

<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/country/has/city
```

</code-block>
<code-block label="Response"> 

```json
[
    {
        "country_id": 1,
        "country": "Afghanistan",
        "last_update": "2006-02-14T23:14:00.000Z",
        "city": [
            {
                "city_id": 251,
                "city": "Kabul",
                "country_id": 1,
                "last_update": "2006-02-14T23:15:25.000Z"
            },
            ...
        ]
    }
]
```
  </code-block>
</code-group>

[⤴️](#hasmany-apis)

### Children of parent

<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/country/1/city
```

</code-block>
<code-block label="Response"> 

```json
[
    {
        "city_id": 251,
        "city": "Kabul",
        "country_id": 1,
        "last_update": "2006-02-14T23:15:25.000Z"
    }
]
```  
  </code-block>
</code-group>

[⤴️](#hasmany-apis)
    
### Insert to child table

<code-group>
  <code-block label="Request" active> 
  
```
POST  /api/v1/country/1/city
```

```json
    {
        "city": "test"
    }
```

</code-block>
<code-block label="Response"> 

```json
{
    "city": "test",
    "country_id": "1",
    "city_id": 10000
}
```
  </code-block>
</code-group>

[⤴️](#hasmany-apis)

### Findone under parent

<code-group>
  <code-block label="Request" active> 

```
GET  /api/v1/country/1/city/findOne?where=(city,like,ka%)
```

</code-block>
<code-block label="Response"> 

```json   
{
    "city": "test",
    "country_id": "1",
    "city_id": 10000
}
```
  </code-block>
</code-group>


[⤴️](#hasmany-apis)

### Child count

<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/country/1/city/count
```

</code-block>
<code-block label="Response"> 

```json
{
    "count": 37
}
```
  </code-block>
</code-group>


[⤴️](#hasmany-apis)

### Get Child By Primary key

<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/country/1/city/251
```

</code-block>
<code-block label="Response"> 

```json
[
    {
        "city_id": 251,
        "city": "Kabul",
        "country_id": 1,
        "last_update": "2006-02-14T23:15:25.000Z"
    }
]
```
  </code-block>
</code-group>


[⤴️](#hasmany-apis)

### Update Child By Primary key

<code-group>
  <code-block label="Request" active> 
  
```
POST  /api/v1/country/1/city/251
```

```
{
    "city": "Kabul-1"
}
```

</code-block>
<code-block label="Response"> 

```json
1
```
  </code-block>
</code-group>


[⤴️](#hasmany-apis)

### Get parent and chlidren within

<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/country/has/city
```

</code-block>
<code-block label="Response"> 

```json
[
    {
        "city_id": 1,
        "city": "sdsdsdsd",
        "country_id": 87,
        "last_update": "2020-01-02T14:50:49.000Z",
        "country": {
            "country_id": 87,
            "country": "Spain",
            "last_update": "2006-02-14T23:14:00.000Z"
        }
    },
    ...
]
```
  </code-block>
</code-group>


[⤴️](#belongsto-apis)

### Get table and parent class within

<code-group>
  <code-block label="Request" active> 
  
```
GET  /api/v1/city/belongs/country
```

</code-block>
<code-block label="Response"> 

```json5
[
    {
        city_id: 1,
        city: "A Corua (La Corua)",
        country_id: 87,
        last_update: "2006-02-15T04:45:25.000Z",
        country: {
        country_id: 87,
        country: "Spain",
        last_update: "2006-02-15T04:44:00.000Z"
    }
]
```
  </code-block>
</code-group>
