66 lines
1.8 KiB
Markdown
66 lines
1.8 KiB
Markdown
# API Examples
|
|
|
|
Soul consists of 4 main namespaces: Tables (`/tables/`), Rows (`/tables/{table-name}/rows/`), Auth (`/auth/`), and Root (`/`). 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 we need to download a sample database and also install Soul CLI.
|
|
|
|
### 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
|
|
npm install # Install dependencies
|
|
npm link # might need `sudo`
|
|
soul -d ./Chinook_Sqlite.sqlite -p 8000
|
|
```
|
|
|
|
</details>
|
|
|
|
## Namespaces
|
|
|
|
1. [/api/tables/](api/tables-examples.md) Examples for Tables endpoints
|
|
2. [/api/{table-name}/rows/](api/rows-examples.md) Examples for Rows endpoints
|
|
3. [/api/auth/](api/auth-examples.md) Examples for Authentication / Authorization endpoints
|
|
1. [/api/{table-name}/rows/](api/rows-auth-examples.md) Examples for Rows endpoints in Auth mode
|
|
4. [/api/](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"
|
|
}
|
|
}
|
|
```
|