From 0a0112c22a548ef52e2504608b9ec739934e7343 Mon Sep 17 00:00:00 2001 From: Vahid Al Date: Thu, 3 Nov 2022 14:13:16 +0330 Subject: [PATCH] table api examples added --- .gitignore | 2 + README.md | 2 + docs/api-examples.md | 63 +++++++++++ docs/api/tables-examples.md | 217 ++++++++++++++++++++++++++++++++++++ 4 files changed, 284 insertions(+) create mode 100644 .gitignore create mode 100644 docs/api-examples.md create mode 100644 docs/api/tables-examples.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b31157c --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +*.db-* +*Chinook* \ No newline at end of file diff --git a/README.md b/README.md index c0910a2..3c6494f 100644 --- a/README.md +++ b/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 diff --git a/docs/api-examples.md b/docs/api-examples.md new file mode 100644 index 0000000..e429192 --- /dev/null +++ b/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 +``` + +
+ Or Using Local Development + +```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 +``` +
+ + +## 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" + } +} +``` diff --git a/docs/api/tables-examples.md b/docs/api/tables-examples.md new file mode 100644 index 0000000..aa2712a --- /dev/null +++ b/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/` 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/` with a `DELETE` endpoint. + +```bash +curl --request DELETE \ + --url http://localhost:8000/api/tables/pets +``` + +Response + +```json +{ "message": "Table deleted" } +```