mirror of https://github.com/nocodb/nocodb
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
147 lines
3.6 KiB
147 lines
3.6 KiB
7 years ago
|
# xmysql: one command to generate REST APIs for **any** MySql database
|
||
|
|
||
|
> Requires node >= 7.6.0
|
||
|
|
||
|
## Why this ?
|
||
|
Deriving REST APIs for a database which do not follow conventions of frameworks such as rails, django etc
|
||
|
is like a small adventure ..
|
||
|
|
||
|
<p align="center">
|
||
|
<img src="https://media.giphy.com/media/8gWrk3QZrjF1C/giphy.gif" alt="Rick & Morty"/>
|
||
|
</p>
|
||
|
|
||
|
Hence this.
|
||
|
|
||
|
Powered by node packages : (express, mysql) => { xmysql }
|
||
|
|
||
|
## FEATURES
|
||
|
* Generates API for **ANY** MySql database
|
||
|
* Serves APIs irrespective of naming conventions of primary keys, foreign keys, tables etc
|
||
|
* CRUD : Usual suspects
|
||
|
* Support for composite primary keys
|
||
|
* Pagination
|
||
|
* Sorting
|
||
|
* Fields
|
||
|
* Relations
|
||
|
* Run dynamic queries
|
||
|
|
||
|
## Sample usage
|
||
|
* npm install -g xmysql
|
||
|
* xmysql -h localhost -u mysqlUsername -p mysqlPassword -d databaseName
|
||
|
* [http://localhost:3000](#http://localhost:3000)
|
||
|
|
||
|
|
||
|
Run HTTP client [Postman](https://www.getpostman.com/) or [similar tools](https://chrome.google.com/webstore/search/http%20client?_category=apps) to invoke REST API calls
|
||
|
|
||
|
## CRUD APIs Usual Suspects
|
||
|
* GET /api/:tableName
|
||
|
* POST /api/:tableName
|
||
|
* GET /api/:tableName/:id
|
||
|
* PUT /api/:tableName/:id
|
||
|
* GET /api/:tableName/count
|
||
|
* GET /api/:tableName/exists
|
||
|
* GET /api/:parentTable/:id/:childTable
|
||
|
* DELETE /api/:tableName/:id
|
||
|
* POST /dynamic
|
||
|
|
||
|
## Other APIS
|
||
|
* GET /api/:tableName/describe
|
||
|
* GET /api/tables
|
||
|
|
||
|
## Support for composite primary keys
|
||
|
|
||
|
#### ___ (three underscores)
|
||
|
|
||
|
```
|
||
|
/api/payments/103___JM555205
|
||
|
```
|
||
|
*___* : If there are multiple primary keys - seperate them by three underscores as shown
|
||
|
|
||
|
## Pagination
|
||
|
|
||
|
#### _p & _size
|
||
|
|
||
|
_p indicates page and _size indicates size of response rows
|
||
|
|
||
|
By default 20 records and max of 100 are returned per GET request on a table.
|
||
|
|
||
|
```
|
||
|
/api/payments?_size=50
|
||
|
```
|
||
|
```
|
||
|
/api/payments?_p=2
|
||
|
```
|
||
|
```
|
||
|
/api/payments?_p=2&_size=50
|
||
|
```
|
||
|
|
||
|
|
||
|
## Sorting
|
||
|
|
||
|
#### _sort
|
||
|
|
||
|
```
|
||
|
/api/payments?_sort=column1
|
||
|
```
|
||
|
eg: sorts ascending by column1
|
||
|
|
||
|
```
|
||
|
/api/payments?_sort=-column1
|
||
|
```
|
||
|
eg: sorts descending by column1
|
||
|
|
||
|
```
|
||
|
/api/payments?_sort=column1,-column2
|
||
|
```
|
||
|
eg: sorts ascending by column1 and descending by column2
|
||
|
|
||
|
|
||
|
## Fields
|
||
|
```
|
||
|
/api/payments?_fields=customerNumber,checkNumber
|
||
|
```
|
||
|
eg: gets only customerNumber and checkNumber in response of each record
|
||
|
```
|
||
|
/api/payments?_fields=-checkNumber
|
||
|
```
|
||
|
eg: gets all fields in table row but not checkNumber
|
||
|
|
||
|
|
||
|
## Run dynamic queries
|
||
|
Dynamic queries on a database can be run by POST method to URL localhost:3000/dynamic
|
||
|
|
||
|
This is enabled only in local i.e -h localhost or -h 127.0.0.1 option.
|
||
|
|
||
|
Post body takes two fields : query and params.
|
||
|
|
||
|
>query: SQL query or SQL prepared query (ones with ?? and ?)
|
||
|
|
||
|
>params : parameters for SQL prepared query
|
||
|
```
|
||
|
POST /dynamic
|
||
|
|
||
|
{
|
||
|
"query": "select * from ?? limit 1,20",
|
||
|
"params": ["customers"]
|
||
|
}
|
||
|
```
|
||
|
## Relational Tables
|
||
|
xmysql identifies foreign key relations automatically and provides GET api.
|
||
|
```
|
||
|
/api/customers/103/payments
|
||
|
```
|
||
|
eg: Customers is parent table and payments is child table. API invocation will result in all payments with customer 103.
|
||
|
|
||
|
|
||
|
## When to use ?
|
||
|
* You need REST APIs without much hassle for (ANY) MySql database
|
||
|
* You are learning new frontend frameworks and need REST APIs for your MySql database.
|
||
|
* You are working on a demo, hacks etc
|
||
|
|
||
|
## When NOT to use ?
|
||
|
* Other times not mentioned in when to use section
|
||
|
|
||
|
|
||
|
|
||
|
|