table api examples added
This commit is contained in:
Vahid Al
2
.gitignore
vendored
Normal file
2
.gitignore
vendored
Normal file
@@ -0,0 +1,2 @@
|
||||
*.db-*
|
||||
*Chinook*
|
||||
@@ -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
|
||||
|
||||
63
docs/api-examples.md
Normal file
63
docs/api-examples.md
Normal file
@@ -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"
|
||||
}
|
||||
}
|
||||
```
|
||||
217
docs/api/tables-examples.md
Normal file
217
docs/api/tables-examples.md
Normal file
@@ -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" }
|
||||
```
|
||||
Reference in New Issue
Block a user