Merge pull request #55 from thevahidal/api-examples-doc-tables

table api examples added

.gitignore

@@ -0,0 +1,2 @@
+*.db-*
+*Chinook*

README.md

@@ -38,6 +38,8 @@ It should return a list of the tables inside `sqlite.db` database.
 ## Documentation
 
 API documentation is available while the project is running at [http://localhost:8000/api/docs](http://localhost:8000/api/docs)
+
+There's also a list of all endpoints examples at [docs/api-examples.md](docs/api-examples.md)
 ## Development
 
 ```bash

docs/api-examples.md

@@ -0,0 +1,63 @@
+# API Examples
+
+Soul is consist of 3 main namespaces: `/tables`, `/rows` and `/`. In this document we'll try to go over all of them so you can get familiar with how Soul works.
+
+## Setup Environment
+
+To follow the below examples run Soul with `sample.db` provided in `examples/` directory:
+
+### Download Sample Database
+
+```bash
+wget https://raw.githubusercontent.com/lerocha/chinook-database/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite # Download sample sqlite database
+```
+### Using Soul CLI
+```bash
+npm install -g soul-cli
+soul -d ./Chinook_Sqlite.sqlite -p 8000
+```
+
+<details>
+  <summary>Or Using Local Development</summary>
+
+```bash
+git clone https://github.com/thevahidal/soul # Clone project
+cd core/
+npm install # Install dependencies
+npm link # might need `sudo` 
+soul -d ./Chinook_Sqlite.sqlite -p 8000
+```
+</details>
+
+
+## Namespaces
+
+1. [/api/tables](/docs/api/tables-examples.md) Examples for Tables endpoints
+2. [/api/rows](/docs/api/rows-examples.md) Examples for Rows endpoints
+3. [/api/](/docs/api/root-examples.md) Examples for Root endpoints
+
+
+## Handling Errors
+
+If an error occurs while processing a request, it will be indicated via the presence of an `error` key and a `message` in the JSON response. For example:
+
+```bash
+curl --request POST \
+  --url http://localhost:8000/api/tables \
+  --header 'Content-Type: application/json' \
+  --data '{
+	"name": "Artist", # note that we already have an `artists` table
+	"schema": [
+		# ...
+	] 
+}'
+```
+
+```json
+{
+	"message": "table artists already exists",
+	"error": {
+		"code": "SQLITE_ERROR"
+	}
+}
+```

docs/api/tables-examples.md

@@ -0,0 +1,217 @@
+## Tables
+
+### 1. List Tables
+
+To list all tables we simply call `/tables` endpoint with `GET` method.
+
+```bash
+curl 'localhost:8000/api/tables'
+```
+
+Response
+
+```json
+{
+  "data": [
+    { "name": "Album" },
+    { "name": "Artist" }
+    // ...
+  ]
+}
+```
+
+#### Query Params
+
+- `_search` e.g. `?_search=art`, to search between tables.
+- `_ordering` e.g. `?_ordering=-name`, to order tables by name descending, or without `-` to sort ascending, e.g. `?_ordering=name`
+
+Example with query params
+
+```bash
+curl 'localhost:8000/api/tables?_search=pl&_ordering=-name'
+```
+
+Response
+
+```json
+{
+  "data": [
+    { "name": "Playlist" },
+    { "name": "PlaylistTrack" },
+    { "name": "Employee" }
+    // ...
+  ]
+}
+```
+
+### 2. Create Tables
+
+To create a new table use the following `POST` endpoint.
+
+```bash
+curl --request POST \
+  --url http://localhost:8000/api/tables \
+  --header 'Content-Type: application/json' \
+  --data '{
+	"name": "pets",
+	"autoAddCreatedAt": true,
+	"autoAddUpdatedAt": false,
+	"schema": [
+		{
+			"name": "name",
+			"type": "Text",
+			"index": true
+		},
+		{
+			"name": "birth_date",
+			"type": "Date",
+			"notNull": true
+		},
+		{
+			"name": "owner_id",
+			"type": "Integer",
+			"foreignKey": {
+				"table": "artists",
+				"column": "ArtistId",
+				"onDelete": "CASCADE",
+				"onUpdate": "CASCADE"
+			}
+		}
+	]
+}'
+
+```
+
+Response
+
+```json
+{
+  "message": "Table created",
+  "data": {
+    "name": "pets",
+    "schema": [
+      {
+        "cid": 0,
+        "name": "createdAt",
+        "type": "DATETIME",
+        "notnull": 0,
+        "dflt_value": "CURRENT_TIMESTAMP",
+        "pk": 0
+      },
+      {
+        "cid": 1,
+        "name": "id",
+        "type": "INTEGER",
+        "notnull": 0,
+        "dflt_value": null,
+        "pk": 1
+      },
+      {
+        "cid": 2,
+        "name": "name",
+        "type": "TEXT",
+        "notnull": 0,
+        "dflt_value": null,
+        "pk": 0
+      },
+      {
+        "cid": 3,
+        "name": "birth_date",
+        "type": "Date",
+        "notnull": 1,
+        "dflt_value": null,
+        "pk": 0
+      },
+      {
+        "cid": 4,
+        "name": "owner_id",
+        "type": "INTEGER",
+        "notnull": 0,
+        "dflt_value": null,
+        "pk": 0
+      }
+    ]
+  }
+}
+```
+
+#### Body Params
+
+- `name` e.g. `name: pets`, to be used as the table name
+- `autoAddCreatedAt` e.g. `autoAddCreatedAt: false` to automatically add a created at field, default `true`
+- `autoAddUpdatedAt` e.g. `autoAddCreatedAt: false` to automatically add a updated at field, default `true`
+- `schema` e.g.
+
+```json
+"schema": [
+	{
+		"name": "name", // field name (required)
+		"type": "TEXT", // field type (required) (one of `TEXT | NUMERIC | INTEGER | REAL | BLOB | BOOLEAN | DATE | DATETIME)
+		"index": true, // should this field be indexed?
+		"default": "John", // field default value
+		"notNull": false, // should this field be non-nullable?
+		"unique": false, // should this field be unique?
+		"primaryKey": true // should this field be the primaryKey? if false Soul will add an auto-increment primary key field
+	},
+	{
+		"name": "user_id",
+		"foreignKey": {
+			"table": "users", // foreign key table
+			"column": "id", // foreign key related field
+			"onDelete": "CASCADE", // on delete constraint (on of CASCADE | SET NULL | SET DEFAULT | RESTRICT)
+			"onUpdate": "CASCADE" // on update constraint (on of CASCADE | SET NULL | SET DEFAULT | RESTRICT)
+		}
+	},
+	// ...
+]
+```
+
+### 3. Get a Table's Schema
+
+To get a table's schema call `/tables/<table-name>` endpoint with `GET` method.
+
+```bash
+curl 'localhost:8000/api/tables/genres'
+```
+
+Response
+
+```json
+{
+  "data": [
+    {
+      "cid": 0,
+      "name": "GenreId",
+      "type": "INTEGER",
+      "notnull": 1,
+      "dflt_value": null,
+      "pk": 1
+    },
+    {
+      "cid": 1,
+      "name": "Name",
+      "type": "NVARCHAR(120)",
+      "notnull": 0,
+      "dflt_value": null,
+      "pk": 0
+    }
+  ]
+}
+```
+
+### 4. Delete / Drop a Table
+
+> CAUTION: Be careful when using this endpoint, it will delete the table and all its data.
+
+To delete a table call `/tables/<table-name>` with a `DELETE` endpoint.
+
+```bash
+curl --request DELETE \
+  --url http://localhost:8000/api/tables/pets
+```
+
+Response
+
+```json
+{ "message": "Table deleted" }
+```