From e30a3b87157fc99892178e5b650a5b088e0d5c48 Mon Sep 17 00:00:00 2001 From: Wing-Kam Wong Date: Mon, 19 Jul 2021 22:35:29 +0800 Subject: [PATCH 1/7] docs: enable table of content Signed-off-by: Wing-Kam Wong --- .../noco-docs/content/en/setup-and-usages/installation.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/packages/noco-docs/content/en/setup-and-usages/installation.md b/packages/noco-docs/content/en/setup-and-usages/installation.md index cbd37ac821..48e68b6991 100644 --- a/packages/noco-docs/content/en/setup-and-usages/installation.md +++ b/packages/noco-docs/content/en/setup-and-usages/installation.md @@ -3,21 +3,20 @@ title: 'Setup and Usages' description: 'Simple installation - takes about three minutes!' position: 1 category: 'Setup and Usages' -fullscreen: true menuTitle: 'Installation' link: https://codesandbox.io/embed/vigorous-firefly-80kq5?hidenavigation=1&theme=dark --- -## Simple installation - takes about three minutes! +Simple installation - takes about three minutes! -### Prerequisites +## Prerequisites - __Must haves__ * [node.js >= 12](https://nodejs.org/en/download) / [Docker](https://www.docker.com/get-started) * [MySql](https://dev.mysql.com/downloads/mysql/) / [Postgres](https://www.postgresql.org/download/) / [SQLserver](https://www.microsoft.com/en-gb/sql-server/sql-server-downloads) / SQLite Database - Nice to haves - Existing schemas can help to create APIs quickly. - - An example database schema can be found : here + - An example database schema can be found here. ## Quick try ### 1-Click Deploy From 56d74d776f7c727d3002ce2ac77b6057b9b15ab5 Mon Sep 17 00:00:00 2001 From: Wing-Kam Wong Date: Mon, 19 Jul 2021 22:42:14 +0800 Subject: [PATCH 2/7] docs: fix broken structures Signed-off-by: Wing-Kam Wong --- .../en/developer-resources/rest-apis.md | 128 ++++++++++-------- 1 file changed, 74 insertions(+), 54 deletions(-) diff --git a/packages/noco-docs/content/en/developer-resources/rest-apis.md b/packages/noco-docs/content/en/developer-resources/rest-apis.md index 1e133ba7ef..242f235fde 100644 --- a/packages/noco-docs/content/en/developer-resources/rest-apis.md +++ b/packages/noco-docs/content/en/developer-resources/rest-apis.md @@ -2,39 +2,33 @@ title: 'REST APIs' position: 1 category: 'Developer Resources' -fullscreen: true menuTitle: 'REST APIs' --- -# Table of Content -* [Features](#features) -* [APIs overview](#api-overview) -* [Authentication](#authentication) -* [Access Control](#acess-control) -* [Migrations](#migrations) - -# Features + +## Features + * **Automatic REST APIs for any SQL database** - * Generates REST APIs for **ANY** MySql, Postgres, MSSQL, Sqlite database :fire: - * Serves APIs irrespective of naming conventions of primary keys, foreign keys, tables etc :fire: - * Support for composite primary keys :fire: - * REST APIs : - * CRUD, List, FindOne, Count, Exists, Distinct (Usual suspects) - * Pagination - * Sorting - * Column filtering - Fields :fire: - * Row filtering - Where :fire: - * Bulk insert, Bulk delete, Bulk read :fire: - * Relations - automatically detected - * Aggregate functions - * More - * Upload single file - * Upload multiple files - * Download file -* **Authentication** -* **Access Control** - - -# API Overview + * 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 + + +## API Overview | **Method** | **Path** | **Query Params** | **Description** | |---|---|---|---| @@ -62,7 +56,6 @@ menuTitle: 'REST APIs' - ### HasMany APIs | **Method** | **Path** | **Query Params** | **Description** | @@ -98,7 +91,7 @@ menuTitle: 'REST APIs' -## Query params +### Query params | **Name** | **Alias** | **Use case** | **Default value** |**Example value** | @@ -140,9 +133,9 @@ like - 'like' - (colName,like,%name) ``` -### Examples +## Examples -#### List +### List @@ -169,7 +162,7 @@ like - 'like' - (colName,like,%name) -#### List + where +### List + where @@ -240,7 +233,7 @@ GET /api/v1/country?where=(country,like,United%)&sort=-country -#### List + where + sort + offset +### List + where + sort + offset @@ -270,7 +263,7 @@ GET /api/v1/country?where=(country,like,United%)&sort=-country&offset=1 -#### List + limit +### List + limit @@ -389,7 +382,10 @@ POST /api/v1/country -```PUT /api/v1/country/1``` +``` +PUT /api/v1/country/1 +``` + ``` { "country": "Afghanistan1" @@ -397,7 +393,7 @@ POST /api/v1/country ``` - + ```json { @@ -429,6 +425,7 @@ true ``` + [⤴️](#api-overview) @@ -629,24 +626,29 @@ GET /api/v1/country/count "count": 161 } ``` -[⤴️](#api-overview) + + +[⤴️](#api-overview) ### Bulk Insert -```POST /api/v1/country/bulk``` +``` +POST /api/v1/country/bulk +``` + ```json - [ - { - "country": "test 1" - }, - { - "country": "test 2" - } - ] +[ + { + "country": "test 1" + }, + { + "country": "test 2" + } +] ``` @@ -659,6 +661,7 @@ GET /api/v1/country/count ``` + [⤴️](#api-overview) @@ -666,7 +669,10 @@ GET /api/v1/country/count -```PUT /api/v1/country/bulk``` +``` +PUT /api/v1/country/bulk +``` + ```json [ { @@ -690,6 +696,7 @@ GET /api/v1/country/count ``` + [⤴️](#api-overview) @@ -698,7 +705,10 @@ GET /api/v1/country/count -```DELETE /api/v1/country/bulk``` +``` +DELETE /api/v1/country/bulk +``` + ```json [ { @@ -720,6 +730,7 @@ GET /api/v1/country/count ``` + [⤴️](#api-overview) @@ -790,7 +801,10 @@ GET /api/v1/country/1/city -```POST /api/v1/country/1/city``` +``` +POST /api/v1/country/1/city +``` + ```json { "city": "test" @@ -817,7 +831,9 @@ GET /api/v1/country/1/city -```GET /api/v1/country/1/city/findOne?where=(city,like,ka%)``` +``` +GET /api/v1/country/1/city/findOne?where=(city,like,ka%) +``` @@ -891,7 +907,10 @@ GET /api/v1/country/1/city/251 -```POST /api/v1/country/1/city/251``` +``` +POST /api/v1/country/1/city/251 +``` + ``` { "city": "Kabul-1" @@ -943,6 +962,7 @@ GET /api/v1/country/has/city [⤴️](#belongsto-apis) + ### Get table and parent class within From 9a121c1a5111450a43d95d407729e47d3a91fc26 Mon Sep 17 00:00:00 2001 From: Wing-Kam Wong Date: Mon, 19 Jul 2021 22:52:42 +0800 Subject: [PATCH 3/7] docs: revise gql page structure Signed-off-by: Wing-Kam Wong --- .../en/developer-resources/graphql-apis.md | 50 ++++++++----------- 1 file changed, 22 insertions(+), 28 deletions(-) diff --git a/packages/noco-docs/content/en/developer-resources/graphql-apis.md b/packages/noco-docs/content/en/developer-resources/graphql-apis.md index 8b9932433d..b504cccb55 100644 --- a/packages/noco-docs/content/en/developer-resources/graphql-apis.md +++ b/packages/noco-docs/content/en/developer-resources/graphql-apis.md @@ -2,31 +2,31 @@ title: 'GraphQL APIs' position: 2 category: 'Developer Resources' -fullscreen: true menuTitle: 'GraphQL APIs' --- -# Features -* APIs - * Generates GraphQL APIs for **ANY** MySql, Postgres, MSSQL, Sqlite database :fire: - * Serves GraphQL queries irrespective of naming conventions of primary keys, foreign keys, tables etc :fire: - * Support for composite primary keys :fire: - * Usual suspects : CRUD, List, FindOne, Count, Exists, Distinct - * Pagination - * Sorting - * Column filtering - Fields :fire: - * Row filtering - Where :fire: - * Bulk insert, Bulk delete, Bulk read :fire: - * Relations - automatically detected - * Aggregate functions - * More - * Upload single file - * Upload multiple files - * Download file + +## Features + +* Generates GraphQL APIs for **ANY** MySql, Postgres, MSSQL, Sqlite database :fire: +* Serves GraphQL queries irrespective of naming conventions of primary keys, foreign keys, tables etc :fire: +* Support for composite primary keys :fire: +* Usual suspects : CRUD, List, FindOne, Count, Exists, Distinct +* Pagination +* Sorting +* Column filtering - Fields :fire: +* Row filtering - Where :fire: +* Bulk insert, Bulk delete, Bulk read :fire: +* Relations - automatically detected +* Aggregate functions +* More + * Upload single file + * Upload multiple files + * Download file * Authentication * Access Control -# GraphQL API Overview +## API Overview ### Query @@ -54,7 +54,7 @@ menuTitle: 'GraphQL APIs' | [TableName**UpdateBulk**](#tablenamebulk) | data: [TableNameInput] | [Int] | Bulk row update | | [TableName**DeleteBulk**](#tablenamedeletebulk) | data: [TableNameInput] | [Int] | Bulk row delete | -## Query Arguments +### Query params | **Param** | **Description** | **Default value** |**Example Value**| |---|---|---|---| @@ -86,7 +86,6 @@ like - 'like' - (colName,like,%name) PaymentList(where:"(checkNumber,eq,JM555205)~or((amount,gt,200)~and(amount,lt,2000))") ``` - #### Logical operators ``` ~or - 'or' @@ -94,6 +93,8 @@ PaymentList(where:"(checkNumber,eq,JM555205)~or((amount,gt,200)~and(amount,lt,20 ~not - 'not' ``` +## Examples + ### TableNameList @@ -243,13 +244,6 @@ CountryList { - - - - - - - #### List + where + sort + offset From 47ff6f3f8819c4472cd5cdf84466c4873588bf16 Mon Sep 17 00:00:00 2001 From: Wing-Kam Wong Date: Mon, 19 Jul 2021 23:08:42 +0800 Subject: [PATCH 4/7] docs: add FAQs page Signed-off-by: Wing-Kam Wong --- .../content/en/getting-started/faqs.md | 57 +++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 packages/noco-docs/content/en/getting-started/faqs.md diff --git a/packages/noco-docs/content/en/getting-started/faqs.md b/packages/noco-docs/content/en/getting-started/faqs.md new file mode 100644 index 0000000000..2b72b299a6 --- /dev/null +++ b/packages/noco-docs/content/en/getting-started/faqs.md @@ -0,0 +1,57 @@ +--- +title: 'FAQs' +description: 'FAQs' +position: 2 +category: 'Getting started' +fullscreen: true +menuTitle: 'FAQs' +--- + +## Which are the supported databases ? + +Currently we supports most ost of the SQL databases Postgres, MySQL, MariaDB, SQL Server and SQLite3. + +## Is it completely free ? + +Currently you can use the product without any cost + +## Which platforms it supports ? + +You can run it any machine with help of Node or Docker + +## Are the APIs secure - does it have Auth and ACL ? + +NocoDB is fully secure with built in session based authentication and authorisation. We currently support Google and Facebook Authorisation. +Authentication also covers things related to email verification, forgot password & reset password. Support for 3rd party Auth libraries Auth0, Firebase, Amazon Cognito will be there in future. + +## Is it possible to ignore certain tables from the view ? + +Yes, you can disable it from the UI + +## Is Access Control List (ACL) or Role Based Access Control (RBAC) ? + +NocoDB not only auto generates access control list for all the tables but also provides GUI to manage these permissions for each category of users and models. Again, these ACL are done in really modular way such that each ACL file is associated with its corresponding router and middleware file. + +ACL/RBAC enables developer to manage fine grained access to underlying models to various category of users. + +## Does APIs have pagination ? + +Yes all APIs have built in pagination. + +## Is there support for Swagger API specification for REST APIs ? + +NocoDB automatically generates swagger documentation for all the REST APIs so that you have to never write one from scartch! Generated documentation is done in a really modular way so that each router file is associated with a swagger documentation. This makes it really easy to follow and update. + +Swagger is the most adapted open source API documentation. Swagger's interactive live documentation not only helps developer to understand APIs but also to invoke the APIs. + +## Can the APIs resist SQL injection attacks ? + +Prepared SQL queries which are safe are executed when data is fetched from Database. + +## How to data validation for models ? + +You can write really complex and data validation function within the models generated for you. + +## I have more questions ? + +Please join our wonderful community at [discord](https://discord.gg/5RgZmkW). \ No newline at end of file From 8361fa9c9a511ad6ab0c137ee7c89777a3be774e Mon Sep 17 00:00:00 2001 From: Wing-Kam Wong Date: Mon, 19 Jul 2021 23:17:12 +0800 Subject: [PATCH 5/7] docs: add env variables page Signed-off-by: Wing-Kam Wong --- .../setup-and-usages/environment-variables.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 packages/noco-docs/content/en/setup-and-usages/environment-variables.md diff --git a/packages/noco-docs/content/en/setup-and-usages/environment-variables.md b/packages/noco-docs/content/en/setup-and-usages/environment-variables.md new file mode 100644 index 0000000000..5d8a4c8cef --- /dev/null +++ b/packages/noco-docs/content/en/setup-and-usages/environment-variables.md @@ -0,0 +1,20 @@ +--- +title: 'Environment Variables' +description: 'Environment Variables' +position: 3 +category: 'Setup and Usages' +fullscreen: true +menuTitle: 'Environment Variables' +--- + +| Variable | Mandatory | Comments | If absent | +|-------------------------|-----------|----------------------------------------------------------------------------------|--------------------------------------------| +| NC_DB | Yes | See our database URLs | A local SQLite will be created in root folder | +| DATABASE_URL | No | JDBC URL Format. Can be used instead of NC_DB. Used in 1-Click Heroku deployment| | +| DATABASE_URL_FILE | No | path to file containing JDBC URL Format. Can be used instead of NC_DB. Used in 1-Click Heroku deployment| | +| NC_PUBLIC_URL | Yes | Used for sending Email invitations | Best guess from http request params | +| NC_AUTH_JWT_SECRET | Yes | JWT secret used for auth and storing other secrets | A Random secret will be generated | +| NC_SENTRY_DSN | No | For Sentry monitoring | | +| NC_CONNECT_TO_EXTERNAL_DB_DISABLED | No | Disable Project creation with external database | | +| NC_DISABLE_TELE | No | Disable telemetry | | +| NC_BACKEND_URL | No | Custom Backend URL | ``http://localhost:8080`` will be used | \ No newline at end of file From 6e444060a357023979b53d4a26e2fd8452576c1a Mon Sep 17 00:00:00 2001 From: Wing-Kam Wong Date: Mon, 19 Jul 2021 23:29:02 +0800 Subject: [PATCH 6/7] docs: include local setup n fix broken structures Signed-off-by: Wing-Kam Wong --- .../en/setup-and-usages/installation.md | 48 ++++++++++++++++--- 1 file changed, 41 insertions(+), 7 deletions(-) diff --git a/packages/noco-docs/content/en/setup-and-usages/installation.md b/packages/noco-docs/content/en/setup-and-usages/installation.md index 48e68b6991..8f34e04396 100644 --- a/packages/noco-docs/content/en/setup-and-usages/installation.md +++ b/packages/noco-docs/content/en/setup-and-usages/installation.md @@ -19,7 +19,9 @@ Simple installation - takes about three minutes! - An example database schema can be found here. ## Quick try -### 1-Click Deploy + +### 1-Click Deploy to Heroku + -### Node app or docker +### Node app / Docker @@ -60,17 +62,49 @@ Simple installation - takes about three minutes! - -

-# Production Setup +## Local Setup + +If you want to modify the source code, there are two scenarios. You can either + +- change backend only or +- change both frontend and backend separately + +Even though the package ``nocodb/packages/nocodb`` is a backend project, you can still visit the dashboard as it includes ``nc-lib-gui``. + +```bash +cd packages/nocodb +npm install +npm run watch:run +# open localhost:8080/dashboard in browser +``` + +As ``nc-lib-gui`` is hosted in npm registry, for local development on frontend part, you should run ``nc-gui`` separately. + +```bash +cd packages/nc-gui +npm install +npm run dev +# open localhost:3000/dashboard in browser +``` + +If you wish to combine the frontend and backend together in your local devlopment environment, you may use ``packages/nc-lib-gui`` as a local depenedency by updating the ``packages/nocodb/package.json`` to + +```json +"nc-lib-gui": "file:../nc-lib-gui" +``` + +In this case, whenever there is any changes made in frontend, you need to run ``npm run build:copy`` under ``packages/nc-gui/``. + +## Production Setup + NocoDB requires a database to store metadata of spreadsheets views and external databases. And connection params for this database can be specified in `NC_DB` environment variable. -## Docker +### Docker @@ -107,7 +141,7 @@ And connection params for this database can be specified in `NC_DB` environment -## Docker Compose +### Docker Compose From a35f2a4340aad2b70f0da98af2ffad3966013b51 Mon Sep 17 00:00:00 2001 From: Wing-Kam Wong Date: Mon, 19 Jul 2021 23:50:13 +0800 Subject: [PATCH 7/7] docs: add apis access Signed-off-by: Wing-Kam Wong --- .../en/setup-and-usages/apis-access.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 packages/noco-docs/content/en/setup-and-usages/apis-access.md diff --git a/packages/noco-docs/content/en/setup-and-usages/apis-access.md b/packages/noco-docs/content/en/setup-and-usages/apis-access.md new file mode 100644 index 0000000000..a31c2d70e2 --- /dev/null +++ b/packages/noco-docs/content/en/setup-and-usages/apis-access.md @@ -0,0 +1,47 @@ +--- +title: 'APIs Access' +description: 'APIs Access' +position: 4 +category: 'Setup and Usages' +menuTitle: 'APIs Access' +--- + +## REST APIs + +- Go to NocoDB Project, click the rightmost button and click ``Copy auth token``. + +![image](https://user-images.githubusercontent.com/35857179/126187328-745943f2-c780-4109-b967-1b3f1c4a1dcd.png) + +- Click the same button and click ``Swagger APIs Doc``. + +![image](https://user-images.githubusercontent.com/35857179/126187534-32c41de9-f17d-4f95-9acc-88aaed044b36.png) + +- Select ``Schemes`` and Click ``Authorize``. + +![image](https://user-images.githubusercontent.com/35857179/126188482-f3aacabf-dbc5-41a8-a190-9f225347ebd1.png) + +- Paste the token you just copy in step 1 and click Authorize + +![image](https://user-images.githubusercontent.com/35857179/126188510-b3790348-6809-4182-911a-a4031ace2fd2.png) + +## GraphQL APIs + +- Go to NocoDB Project, click the rightmost button and click ``Copy auth token``. + +![image](https://user-images.githubusercontent.com/35857179/126187624-03ee550d-71eb-499f-ad8b-54e32a94f729.png) + +- Click the same button and click ``GraphQL APIs`. + +![image](https://user-images.githubusercontent.com/35857179/126187581-22503b8d-f6dd-4a4e-8b12-a475c27354a2.png) + +- Click ``REQUEST HEADERS``. + +![image](https://user-images.githubusercontent.com/35857179/126188122-1aa7b153-f05a-46fd-953b-751376d708bf.png) + +- Paste the token you just copy in step 1. + +```json +{ + "xc-auth": "YOUR_AUTH_TOKEN" +} +``` \ No newline at end of file