Browse Source

doc : update

pull/13/head
oof1lab 7 years ago
parent
commit
3da5e3c0c0
  1. 102
      README.md

102
README.md

@ -90,41 +90,31 @@ Download [node](https://nodejs.org/en/download/current/),
if you haven't on your system. if you haven't on your system.
## Usual Suspects in a REST API framework ## API Overview
| HTTP Type | API URL | Comments | |# | HTTP Type | API URL | Comments |
|-----------|----------------------------------|--------------------------------------------------------- |--|-----------|----------------------------------|---------------------------------------------------------
| GET | / | Gets all REST APIs | |01| GET | / | Gets all REST APIs |
| GET | /api/tableName | Lists rows of table | |02| GET | /api/tableName | Lists rows of table |
| POST | /api/tableName | Create a new row | |03| POST | /api/tableName | Create a new row |
| PUT | /api/tableName | Replaces existing row with new row | |04| PUT | /api/tableName | Replaces existing row with new row |
| GET | /api/tableName/:id | Retrieves a row by primary key | |05| GET | /api/tableName/:id | Retrieves a row by primary key |
| PATCH | /api/tableName/:id | Updates a row by primary key | |06| PATCH | /api/tableName/:id | Updates a row by primary key |
| GET | /api/tableName/findOne | Works as list but gets single record matching criteria | |07| GET | /api/tableName/findOne | Works as list but gets single record matching criteria |
| GET | /api/tableName/count | Count number of rows in a table | |08| GET | /api/tableName/count | Count number of rows in a table |
| GET | /api/tableName/:id/exists | True or false whether a row exists or not | |09| GET | /api/tableName/:id/exists | True or false whether a row exists or not |
| DELETE | /api/tableName/:id | Delete a row by primary key | |10| DELETE | /api/tableName/:id | Delete a row by primary key |
| GET | [/api/parentTable/:id/childTable](#relational-tables) | Get list of child table rows with parent table foreign key | |11| GET | [/api/parentTable/:id/childTable](#relational-tables) | Get list of child table rows with parent table foreign key |
|12| GET :fire:| [/api/tableName/aggregate](#aggregate-functions) | Aggregate results of numeric column(s) |
## APIs with HOT features |13| GET :fire:| [/api/tableName/groupby](#group-by-having-as-api) | Group by results of column(s) |
|14| GET :fire:| [/api/tableName/ugroupby](#union-of-multiple-group-by-statements) | Multiple group by results using one call |
| HTTP Type | API URL | Comments | |15| GET :fire:| [/api/tableName/chart](#chart) | Numeric column distribution based on (min,max,step) or(step array) or (automagic)|
|-----------|----------------------------------|--------------------------------------------------------- |16| GET :fire:| [/dynamic](#run-dynamic-queries) | execute dynamic mysql statements with params |
| GET | /api/tableName/aggregate | Aggregate results of numeric column(s) | |17| GET :fire:| [/upload](#upload-single-file) | upload single file |
| GET :fire:| /api/tableName/groupby | Group by results of column(s) | |18| GET :fire:| [/uploads](#upload-multiple-files) | upload multiple files |
| GET :fire:| /api/tableName/ugroupby | Multiple group by results using one call | |19| GET :fire:| [/download](#download-file) | download a file |
| GET :fire:| /api/tableName/chart | Numeric column distribution based on (min,max,step) or(step array) or (automagic)| |20| GET | /api/tableName/describe| describe each table for its columns |
|21| GET | /api/tables| get all tables in database |
## APIs for Prototyping :snowboarder: :snowboarder:
| HTTP Type | API URL | Comments |
|-----------|----------------------------------|---------------------------------------------------------
| GET :fire:| /dynamic | execute dynamic mysql statements with params |
| GET :fire:| /upload | upload single file |
| GET :fire:| /uploads | upload multiple files |
| GET :fire:| /download | download a file |
| GET :fire:| /api/tableName/describe | describe each table for its columns |
| GET :fire:| /api/tables | get all tables in database |
@ -134,6 +124,7 @@ xmysql identifies foreign key relations automatically and provides GET api.
/api/blogs/103/comments /api/blogs/103/comments
``` ```
eg: blogs is parent table and comments is child table. API invocation will result in all comments for blog primary key 103. eg: blogs is parent table and comments is child table. API invocation will result in all comments for blog primary key 103.
[:arrow_heading_up:](#api-overview)
## Support for composite primary keys ## Support for composite primary keys
@ -249,6 +240,7 @@ eg: filter of rows using _where is available for relational route URLs too.
/api/tableName/findOne?_where=(id,eq,1) /api/tableName/findOne?_where=(id,eq,1)
``` ```
Works similar to list but only returns top/one result. Used in conjunction with _where Works similar to list but only returns top/one result. Used in conjunction with _where
[:arrow_heading_up:](#api-overview)
## Count ## Count
``` ```
@ -256,6 +248,7 @@ Works similar to list but only returns top/one result. Used in conjunction with
``` ```
Returns number of rows in table Returns number of rows in table
[:arrow_heading_up:](#api-overview)
## Exists ## Exists
``` ```
@ -263,9 +256,10 @@ Returns number of rows in table
``` ```
Returns true or false depending on whether record exists Returns true or false depending on whether record exists
[:arrow_heading_up:](#api-overview)
## Group By Having as query params
## Group By, Having (as query params) [:arrow_heading_up:](#api-overview)
``` ```
/api/offices?_groupby=country /api/offices?_groupby=country
@ -278,7 +272,8 @@ eg: SELECT country,count(*) FROM offices GROUP BY country
eg: SELECT country,count(1) as _count FROM offices GROUP BY country having _count > 1 eg: SELECT country,count(1) as _count FROM offices GROUP BY country having _count > 1
## Group By, Having (as a seperate route) ## Group By Having as API
[:arrow_heading_up:](#api-overview)
``` ```
/api/offices/groupby?_fields=country /api/offices/groupby?_fields=country
@ -296,7 +291,8 @@ eg: SELECT country,city,count(*) FROM offices GROUP BY country,city
eg: SELECT country,city,count(*) as _count FROM offices GROUP BY country,city having _count > 1 eg: SELECT country,city,count(*) as _count FROM offices GROUP BY country,city having _count > 1
## Group By, Order By ### Group By, Order By
[:arrow_heading_up:](#api-overview)
``` ```
/api/offices/groupby?_fields=country,city&sort=city /api/offices/groupby?_fields=country,city&sort=city
@ -315,6 +311,7 @@ eg: SELECT country,city,count(*) FROM offices GROUP BY country,city ORDER BY cit
## Aggregate functions ## Aggregate functions
[:arrow_heading_up:](#api-overview)
``` ```
http://localhost:3000/api/payments/aggregate?_fields=amount http://localhost:3000/api/payments/aggregate?_fields=amount
@ -358,7 +355,10 @@ response body
eg: retrieves numeric aggregate can be done for multiple columns too eg: retrieves numeric aggregate can be done for multiple columns too
## Union of many group by statements :fire::fire:**[ HOTNESS ALERT ]** ## Union of multiple group by statements
[:arrow_heading_up:](#api-overview)
:fire::fire:**[ HOTNESS ALERT ]**
Group by multiple columns in one API call using _fields query params - comes really handy Group by multiple columns in one API call using _fields query params - comes really handy
@ -417,13 +417,17 @@ response body
``` ```
## Chart :fire::fire: **[ HOTNESS ALERT ]** ## Chart
[:arrow_heading_up:](#api-overview)
:fire::fire: **[ HOTNESS ALERT ]**
Chart API returns distribution of a numeric column in a table Chart API returns distribution of a numeric column in a table
It comes in three flavours It comes in three flavours
1. Chart : With min, max, step in query params :fire::fire: 1. Chart : With min, max, step in query params :fire::fire:
[:arrow_heading_up:](#api-overview)
This API returns the number of rows where amount is between (0,25000), (25001,50000) ... This API returns the number of rows where amount is between (0,25000), (25001,50000) ...
@ -462,6 +466,7 @@ Response
``` ```
2. Chart : With step array in params :fire::fire: 2. Chart : With step array in params :fire::fire:
[:arrow_heading_up:](#api-overview)
This API returns distribution between the step array specified This API returns distribution between the step array specified
@ -493,6 +498,7 @@ Response
``` ```
3. Chart : with no params :fire::fire: 3. Chart : with no params :fire::fire:
[:arrow_heading_up:](#api-overview)
This API figures out even distribution of a numeric column in table and returns the data This API figures out even distribution of a numeric column in table and returns the data
@ -538,6 +544,8 @@ _fields in Chart API can only take numeric column as its argument.
## Run dynamic queries ## Run dynamic queries
[:arrow_heading_up:](#api-overview)
Dynamic queries on a database can be run by POST method to URL localhost:3000/dynamic Dynamic queries on a database can be run by POST method to URL localhost:3000/dynamic
This is enabled only when using local mysql server i.e -h localhost or -h 127.0.0.1 option. This is enabled only when using local mysql server i.e -h localhost or -h 127.0.0.1 option.
@ -570,6 +578,7 @@ POST /dynamic/user/update
## Upload single file ## Upload single file
[:arrow_heading_up:](#api-overview)
``` ```
POST /upload POST /upload
@ -584,6 +593,8 @@ returns uploaded file name else 'upload failed'
## Upload multiple files ## Upload multiple files
[:arrow_heading_up:](#api-overview)
``` ```
POST /uploads POST /uploads
``` ```
@ -596,21 +607,28 @@ eg: curl --form files=@/Users/me/Desktop/a.png --form files=@/Users/me/Desktop/b
returns uploaded file names as string returns uploaded file names as string
## Download file ## Download file
[:arrow_heading_up:](#api-overview)
http://localhost:3000/download?name=fileName http://localhost:3000/download?name=fileName
> For upload and download of files -> you can specify storage folder using -s option > For upload and download of files -> you can specify storage folder using -s option
> Upload and download apis are available only with local mysql server > Upload and download apis are available only with local mysql server
## When to use ? ## When to use ?
[:arrow_heading_up:](#api-overview)
* You need just REST APIs without much hassle for (ANY) MySql database. * You need just 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 learning new frontend frameworks and need REST APIs for your MySql database.
* You are working on a demo, hacks etc * You are working on a demo, hacks etc
## When NOT to use ? ## When NOT to use ?
[:arrow_heading_up:](#api-overview)
* If you are in need of a full blown MVC framework, ACL, Authorisation etc - its early days please watch/star this repo. Thank you. * If you are in need of a full blown MVC framework, ACL, Authorisation etc - its early days please watch/star this repo. Thank you.
### Command line options ### Command line options
[:arrow_heading_up:](#api-overview)
``` ```
Options: Options:
@ -647,6 +665,7 @@ http://localhost:3000/download?name=fileName
# Docker # Docker
[:arrow_heading_up:](#api-overview)
Simply build with `docker build -t xmysql .` and run with `docker run -p 3000:3000 -d xmysql` Simply build with `docker build -t xmysql .` and run with `docker run -p 3000:3000 -d xmysql`
@ -674,6 +693,7 @@ ENV DATABASE_NAME sakila
# Tests : setup on local machine # Tests : setup on local machine
[:arrow_heading_up:](#api-overview)
Login to mysql shell Login to mysql shell

Loading…
Cancel
Save