soul-cli 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.all-contributorsrc +73 -0
- package/.editorconfig +26 -0
- package/.env.sample +9 -0
- package/.eslintignore +2 -0
- package/.eslintrc.js +24 -0
- package/.github/ISSUE_TEMPLATE/bug_report.md +38 -0
- package/.github/ISSUE_TEMPLATE/feature_request.md +20 -0
- package/.github/workflows/npm-publish.yml +23 -0
- package/.husky/pre-commit +5 -0
- package/CONTRIBUTING.md +92 -0
- package/LICENSE +21 -0
- package/README.md +186 -1
- package/docs/api/root-examples.md +41 -0
- package/docs/api/rows-examples.md +225 -0
- package/docs/api/tables-examples.md +217 -0
- package/docs/api-examples.md +62 -0
- package/docs/extensions-examples.md +167 -0
- package/docs/logo.png +0 -0
- package/docs/soul-studio.png +0 -0
- package/docs/ws/rows-examples.md +122 -0
- package/docs/ws-examples.md +42 -0
- package/package.json +17 -2
- package/src/cli.js +59 -1
- package/src/commands.js +22 -0
- package/src/config/index.js +48 -3
- package/src/constants/api.js +26 -0
- package/src/constants/auth.js +5 -0
- package/src/constants/index.js +13 -0
- package/src/constants/messages.js +41 -0
- package/src/constants/roles.js +3 -0
- package/src/constants/tables.js +47 -0
- package/src/controllers/auth/common.js +16 -0
- package/src/controllers/auth/index.js +5 -0
- package/src/controllers/auth/tables.js +96 -0
- package/src/controllers/auth/token.js +243 -0
- package/src/controllers/auth/user.js +394 -0
- package/src/controllers/auth.test.js +372 -0
- package/src/controllers/rows.js +30 -31
- package/src/controllers/rows.test.js +209 -18
- package/src/controllers/tables.test.js +58 -28
- package/src/db/schema.js +118 -0
- package/src/index.js +32 -7
- package/src/middlewares/api.js +79 -0
- package/src/middlewares/auth.js +85 -0
- package/src/middlewares/broadcast.js +1 -1
- package/src/middlewares/validation.js +3 -2
- package/src/routes/auth.js +29 -0
- package/src/routes/rows.js +17 -5
- package/src/routes/tables.js +26 -4
- package/src/schemas/auth.js +67 -0
- package/src/schemas/index.js +6 -1
- package/src/schemas/rows.js +20 -0
- package/src/schemas/tables.js +18 -2
- package/src/server.js +3 -2
- package/src/services/authService.js +78 -0
- package/src/services/index.js +2 -1
- package/src/services/rowService.js +36 -7
- package/src/services/tableService.js +127 -1
- package/src/swagger/index.js +67 -0
- package/src/swagger/swagger.json +292 -60
- package/src/tests/index.js +4 -5
- package/src/tests/testData.js +72 -27
- package/src/utils/index.js +78 -0
- /package/{src/services/.gitkeep → docs/extensions/api-examples.js} +0 -0
|
@@ -0,0 +1,225 @@
|
|
|
1
|
+
## Rows
|
|
2
|
+
|
|
3
|
+
### 1. List Rows of a Table
|
|
4
|
+
|
|
5
|
+
To list all (or some of) rows we simply call `/tables/<table-name>/rows/` endpoint with `GET` method.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
curl 'localhost:8000/api/tables/Album/rows/'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Response
|
|
12
|
+
|
|
13
|
+
```json
|
|
14
|
+
{
|
|
15
|
+
"data": [
|
|
16
|
+
{
|
|
17
|
+
"AlbumId": 1,
|
|
18
|
+
"Title": "For Those About To Rock We Salute You",
|
|
19
|
+
"ArtistId": 1
|
|
20
|
+
},
|
|
21
|
+
{ "AlbumId": 2, "Title": "Balls to the Wall", "ArtistId": 2 }
|
|
22
|
+
// ...
|
|
23
|
+
],
|
|
24
|
+
"total": 347,
|
|
25
|
+
"next": "/tables/Album?page=2",
|
|
26
|
+
"previous": null
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
#### Query Params
|
|
31
|
+
|
|
32
|
+
- `_page` e.g. `?_page=2`, to get the second page of results.
|
|
33
|
+
- `_limit` e.g. `?_limit=20`, to get 20 results per page.
|
|
34
|
+
- `_search` e.g. `?_search=rock`, to search across all fields.
|
|
35
|
+
- `_ordering` e.g. `?_ordering=-Title`, to order rows by title descending, or without `-` to sort ascending, e.g. `?_ordering=Title`
|
|
36
|
+
- `_schema` e.g. `?_schema=Title,ArtistId`, to get only the Title and ArtistId columns.
|
|
37
|
+
- `_extend` e.g. `?_extend=ArtistId`, to get the Artist object related to the Album.
|
|
38
|
+
- `_filters` e.g. `?_filters=ArtistId:[1,2,3],Title:Rock`, to get only the rows where the ArtistId can be 1,2 or 3 and the Title is Rock.
|
|
39
|
+
NOTE: If you want to use comparison operators in the filter, you can use these operators after the field: `__eq, __neq, __lt, __gt, __lte, __gte, __null, __notnull` . For example, you can use `/invoices/rows?_filters=InvoiceId__neq:1,Total__gte:5,BillingPostalCode__notnull`
|
|
40
|
+
|
|
41
|
+
Example with query params
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
curl 'localhost:8000/api/tables/Album/rows?_page=1&_limit=20&_search=rock&_ordering=-Title&_schema=Title,ArtistId&_extend=ArtistId&_filters=ArtistId:90'
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Response
|
|
48
|
+
|
|
49
|
+
```json
|
|
50
|
+
{
|
|
51
|
+
"data": [
|
|
52
|
+
{
|
|
53
|
+
"Title": "Rock In Rio [CD2]",
|
|
54
|
+
"ArtistId": 90,
|
|
55
|
+
"ArtistId_data": { "ArtistId": 90, "Name": "Iron Maiden" }
|
|
56
|
+
},
|
|
57
|
+
{
|
|
58
|
+
"Title": "Rock In Rio [CD1]",
|
|
59
|
+
"ArtistId": 90,
|
|
60
|
+
"ArtistId_data": { "ArtistId": 90, "Name": "Iron Maiden" }
|
|
61
|
+
}
|
|
62
|
+
],
|
|
63
|
+
"total": 2,
|
|
64
|
+
"next": null,
|
|
65
|
+
"previous": null
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### 2. Insert a New Row
|
|
70
|
+
|
|
71
|
+
To insert a new row to a `table` call `/tables/<table-name>/rows/` endpoint with `POST` method.
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
curl --request POST \
|
|
75
|
+
--url http://localhost:8000/api/tables/Employee/rows \
|
|
76
|
+
--header 'Content-Type: application/json' \
|
|
77
|
+
--data '{
|
|
78
|
+
"fields": {
|
|
79
|
+
"FirstName": "Damien",
|
|
80
|
+
"LastName": "Rice"
|
|
81
|
+
}
|
|
82
|
+
}'
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Response
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
{
|
|
89
|
+
"message": "Row inserted",
|
|
90
|
+
"data": {
|
|
91
|
+
"changes": 1,
|
|
92
|
+
"lastInsertRowid": 9
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
#### Body Params
|
|
98
|
+
|
|
99
|
+
- `fields` e.g.
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
"fields": {
|
|
103
|
+
// fields values for the new row
|
|
104
|
+
}
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
### 3. Get Row(s) by ID
|
|
108
|
+
|
|
109
|
+
To get a row call `/tables/<table-name>/rows/<lookup-values>/` endpoint with `GET` method.
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
curl http://localhost:8000/api/tables/Album/rows/1/
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Response
|
|
116
|
+
|
|
117
|
+
```json
|
|
118
|
+
{
|
|
119
|
+
"data": {
|
|
120
|
+
"AlbumId": 1,
|
|
121
|
+
"Title": "For Those About To Rock We Salute You",
|
|
122
|
+
"ArtistId": 1
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
#### Path Params
|
|
128
|
+
|
|
129
|
+
- `lookup-values` e.g. `1`, to get the row with the AlbumId 1. or comma-separated values e.g. `1,2`, to get the rows with the AlbumId 1 and 2. (Bulk Retrieve)
|
|
130
|
+
|
|
131
|
+
#### Query Params
|
|
132
|
+
|
|
133
|
+
- `_lookup_field` e.g. `?_lookup_field=ArtistId`, to get the row by the ArtistId field. If not provided, the default lookup field is the primary key of the table.
|
|
134
|
+
- `_schema` e.g. `?_schema=Title,ArtistId`, to get only the Title and ArtistId columns.
|
|
135
|
+
- `_extend` e.g. `?_extend=ArtistId`, to get the Artist object related to the Album.
|
|
136
|
+
|
|
137
|
+
Example with query params
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
curl 'http://localhost:8000/api/tables/Album/rows/Facelift?_lookup_field=Title&_extend=ArtistId&_schema=Title'
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Response
|
|
144
|
+
|
|
145
|
+
```json
|
|
146
|
+
{
|
|
147
|
+
"data": {
|
|
148
|
+
"Title": "Facelift",
|
|
149
|
+
"ArtistId_data": {
|
|
150
|
+
"ArtistId": 5,
|
|
151
|
+
"Name": "Alice In Chains"
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### 4. Update Row(s) by ID
|
|
158
|
+
|
|
159
|
+
To update a row call `/tables/<table-name>/rows/<lookup-values>/` endpoint with `PUT` method.
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
curl --request PUT \
|
|
163
|
+
--url http://localhost:8000/api/tables/Album/rows/7 \
|
|
164
|
+
--header 'Content-Type: application/json' \
|
|
165
|
+
--data '{
|
|
166
|
+
"fields": {
|
|
167
|
+
"Title": "FaceElevate"
|
|
168
|
+
}
|
|
169
|
+
}'
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Response
|
|
173
|
+
|
|
174
|
+
```json
|
|
175
|
+
{
|
|
176
|
+
"message": "Row updated"
|
|
177
|
+
}
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
#### Path Params
|
|
181
|
+
|
|
182
|
+
- `lookup-values` e.g. `1`, to update the row with the AlbumId 1. or comma-separated values e.g. `1,2`, to update the rows with the AlbumId 1 and 2. (Bulk Update)
|
|
183
|
+
|
|
184
|
+
#### Query Params
|
|
185
|
+
|
|
186
|
+
- `_lookup_field` e.g. `?_lookup_field=ArtistId`, to update the row by the ArtistId field. If not provided, the default lookup field is the primary key of the table.
|
|
187
|
+
|
|
188
|
+
#### Body Params
|
|
189
|
+
|
|
190
|
+
- `fields` e.g.
|
|
191
|
+
|
|
192
|
+
```json
|
|
193
|
+
"fields": {
|
|
194
|
+
// fields values to update
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
### 5. Delete Row(s) by ID
|
|
199
|
+
|
|
200
|
+
To delete a row call `/tables/<table-name>/rows/<lookup-values>/` endpoint with `DELETE` method.
|
|
201
|
+
|
|
202
|
+
```bash
|
|
203
|
+
curl --request DELETE \
|
|
204
|
+
--url http://localhost:8000/api/tables/PlaylistTrack/rows/1
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
Response
|
|
208
|
+
|
|
209
|
+
```json
|
|
210
|
+
{
|
|
211
|
+
"message": "Row deleted",
|
|
212
|
+
"data": {
|
|
213
|
+
"changes": 3290,
|
|
214
|
+
"lastInsertRowid": 0
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
#### Path Params
|
|
220
|
+
|
|
221
|
+
- `lookup-values` e.g. `1`, to delete the row with the AlbumId 1. or comma-separated values e.g. `1,2`, to delete the rows with the AlbumId 1 and 2. (Bulk Delete)
|
|
222
|
+
|
|
223
|
+
#### Query Params
|
|
224
|
+
|
|
225
|
+
- `_lookup_field` e.g. `?_lookup_field=ArtistId`, to delete the row by the ArtistId field. If not provided, the default lookup field is the primary key of the table.
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
## Tables
|
|
2
|
+
|
|
3
|
+
### 1. List Tables
|
|
4
|
+
|
|
5
|
+
To list all tables we simply call `/tables` endpoint with `GET` method.
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
curl 'localhost:8000/api/tables'
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Response
|
|
12
|
+
|
|
13
|
+
```json
|
|
14
|
+
{
|
|
15
|
+
"data": [
|
|
16
|
+
{ "name": "Album" },
|
|
17
|
+
{ "name": "Artist" }
|
|
18
|
+
// ...
|
|
19
|
+
]
|
|
20
|
+
}
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
#### Query Params
|
|
24
|
+
|
|
25
|
+
- `_search` e.g. `?_search=art`, to search between tables.
|
|
26
|
+
- `_ordering` e.g. `?_ordering=-name`, to order tables by name descending, or without `-` to sort ascending, e.g. `?_ordering=name`
|
|
27
|
+
|
|
28
|
+
Example with query params
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
curl 'localhost:8000/api/tables?_search=pl&_ordering=-name'
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Response
|
|
35
|
+
|
|
36
|
+
```json
|
|
37
|
+
{
|
|
38
|
+
"data": [
|
|
39
|
+
{ "name": "Playlist" },
|
|
40
|
+
{ "name": "PlaylistTrack" },
|
|
41
|
+
{ "name": "Employee" }
|
|
42
|
+
// ...
|
|
43
|
+
]
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
### 2. Create Tables
|
|
48
|
+
|
|
49
|
+
To create a new table use the following `POST` endpoint.
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
curl --request POST \
|
|
53
|
+
--url http://localhost:8000/api/tables \
|
|
54
|
+
--header 'Content-Type: application/json' \
|
|
55
|
+
--data '{
|
|
56
|
+
"name": "pets",
|
|
57
|
+
"autoAddCreatedAt": true,
|
|
58
|
+
"autoAddUpdatedAt": false,
|
|
59
|
+
"schema": [
|
|
60
|
+
{
|
|
61
|
+
"name": "name",
|
|
62
|
+
"type": "Text",
|
|
63
|
+
"index": true
|
|
64
|
+
},
|
|
65
|
+
{
|
|
66
|
+
"name": "birth_date",
|
|
67
|
+
"type": "Date",
|
|
68
|
+
"notNull": true
|
|
69
|
+
},
|
|
70
|
+
{
|
|
71
|
+
"name": "owner_id",
|
|
72
|
+
"type": "Integer",
|
|
73
|
+
"foreignKey": {
|
|
74
|
+
"table": "artists",
|
|
75
|
+
"column": "ArtistId",
|
|
76
|
+
"onDelete": "CASCADE",
|
|
77
|
+
"onUpdate": "CASCADE"
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
]
|
|
81
|
+
}'
|
|
82
|
+
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Response
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
{
|
|
89
|
+
"message": "Table created",
|
|
90
|
+
"data": {
|
|
91
|
+
"name": "pets",
|
|
92
|
+
"schema": [
|
|
93
|
+
{
|
|
94
|
+
"cid": 0,
|
|
95
|
+
"name": "createdAt",
|
|
96
|
+
"type": "DATETIME",
|
|
97
|
+
"notnull": 0,
|
|
98
|
+
"dflt_value": "CURRENT_TIMESTAMP",
|
|
99
|
+
"pk": 0
|
|
100
|
+
},
|
|
101
|
+
{
|
|
102
|
+
"cid": 1,
|
|
103
|
+
"name": "id",
|
|
104
|
+
"type": "INTEGER",
|
|
105
|
+
"notnull": 0,
|
|
106
|
+
"dflt_value": null,
|
|
107
|
+
"pk": 1
|
|
108
|
+
},
|
|
109
|
+
{
|
|
110
|
+
"cid": 2,
|
|
111
|
+
"name": "name",
|
|
112
|
+
"type": "TEXT",
|
|
113
|
+
"notnull": 0,
|
|
114
|
+
"dflt_value": null,
|
|
115
|
+
"pk": 0
|
|
116
|
+
},
|
|
117
|
+
{
|
|
118
|
+
"cid": 3,
|
|
119
|
+
"name": "birth_date",
|
|
120
|
+
"type": "Date",
|
|
121
|
+
"notnull": 1,
|
|
122
|
+
"dflt_value": null,
|
|
123
|
+
"pk": 0
|
|
124
|
+
},
|
|
125
|
+
{
|
|
126
|
+
"cid": 4,
|
|
127
|
+
"name": "owner_id",
|
|
128
|
+
"type": "INTEGER",
|
|
129
|
+
"notnull": 0,
|
|
130
|
+
"dflt_value": null,
|
|
131
|
+
"pk": 0
|
|
132
|
+
}
|
|
133
|
+
]
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
#### Body Params
|
|
139
|
+
|
|
140
|
+
- `name` e.g. `name: pets`, to be used as the table name
|
|
141
|
+
- `autoAddCreatedAt` e.g. `autoAddCreatedAt: false` to automatically add a created at field, default `true`
|
|
142
|
+
- `autoAddUpdatedAt` e.g. `autoAddCreatedAt: false` to automatically add a updated at field, default `true`
|
|
143
|
+
- `schema` e.g.
|
|
144
|
+
|
|
145
|
+
```json
|
|
146
|
+
"schema": [
|
|
147
|
+
{
|
|
148
|
+
"name": "name", // field name (required)
|
|
149
|
+
"type": "TEXT", // field type (required) (one of `TEXT | NUMERIC | INTEGER | REAL | BLOB | BOOLEAN | DATE | DATETIME)
|
|
150
|
+
"index": true, // should this field be indexed?
|
|
151
|
+
"default": "John", // field default value
|
|
152
|
+
"notNull": false, // should this field be non-nullable?
|
|
153
|
+
"unique": false, // should this field be unique?
|
|
154
|
+
"primaryKey": true // should this field be the primaryKey? if false Soul will add an auto-increment primary key field
|
|
155
|
+
},
|
|
156
|
+
{
|
|
157
|
+
"name": "user_id",
|
|
158
|
+
"foreignKey": {
|
|
159
|
+
"table": "users", // foreign key table
|
|
160
|
+
"column": "id", // foreign key related field
|
|
161
|
+
"onDelete": "CASCADE", // on delete constraint (on of CASCADE | SET NULL | SET DEFAULT | RESTRICT)
|
|
162
|
+
"onUpdate": "CASCADE" // on update constraint (on of CASCADE | SET NULL | SET DEFAULT | RESTRICT)
|
|
163
|
+
}
|
|
164
|
+
},
|
|
165
|
+
// ...
|
|
166
|
+
]
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### 3. Get a Table's Schema
|
|
170
|
+
|
|
171
|
+
To get a table's schema call `/tables/<table-name>` endpoint with `GET` method.
|
|
172
|
+
|
|
173
|
+
```bash
|
|
174
|
+
curl 'localhost:8000/api/tables/genres'
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Response
|
|
178
|
+
|
|
179
|
+
```json
|
|
180
|
+
{
|
|
181
|
+
"data": [
|
|
182
|
+
{
|
|
183
|
+
"cid": 0,
|
|
184
|
+
"name": "GenreId",
|
|
185
|
+
"type": "INTEGER",
|
|
186
|
+
"notnull": 1,
|
|
187
|
+
"dflt_value": null,
|
|
188
|
+
"pk": 1
|
|
189
|
+
},
|
|
190
|
+
{
|
|
191
|
+
"cid": 1,
|
|
192
|
+
"name": "Name",
|
|
193
|
+
"type": "NVARCHAR(120)",
|
|
194
|
+
"notnull": 0,
|
|
195
|
+
"dflt_value": null,
|
|
196
|
+
"pk": 0
|
|
197
|
+
}
|
|
198
|
+
]
|
|
199
|
+
}
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
### 4. Delete / Drop a Table
|
|
203
|
+
|
|
204
|
+
> CAUTION: Be careful when using this endpoint, it will delete the table and all its data.
|
|
205
|
+
|
|
206
|
+
To delete a table call `/tables/<table-name>` with a `DELETE` endpoint.
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
curl --request DELETE \
|
|
210
|
+
--url http://localhost:8000/api/tables/pets
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Response
|
|
214
|
+
|
|
215
|
+
```json
|
|
216
|
+
{ "message": "Table deleted" }
|
|
217
|
+
```
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# API Examples
|
|
2
|
+
|
|
3
|
+
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.
|
|
4
|
+
|
|
5
|
+
## Setup Environment
|
|
6
|
+
|
|
7
|
+
To follow the below examples we need to download a sample database and also install Soul CLI.
|
|
8
|
+
|
|
9
|
+
### Download Sample Database
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
wget https://raw.githubusercontent.com/lerocha/chinook-database/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite # Download sample sqlite database
|
|
13
|
+
```
|
|
14
|
+
### Using Soul CLI
|
|
15
|
+
```bash
|
|
16
|
+
npm install -g soul-cli
|
|
17
|
+
soul -d ./Chinook_Sqlite.sqlite -p 8000
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
<details>
|
|
21
|
+
<summary>Or Using Local Development</summary>
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
git clone https://github.com/thevahidal/soul # Clone project
|
|
25
|
+
npm install # Install dependencies
|
|
26
|
+
npm link # might need `sudo`
|
|
27
|
+
soul -d ./Chinook_Sqlite.sqlite -p 8000
|
|
28
|
+
```
|
|
29
|
+
</details>
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
## Namespaces
|
|
33
|
+
|
|
34
|
+
1. [/api/tables](/docs/api/tables-examples.md) Examples for Tables endpoints
|
|
35
|
+
2. [/api/rows](/docs/api/rows-examples.md) Examples for Rows endpoints
|
|
36
|
+
3. [/api/](/docs/api/root-examples.md) Examples for Root endpoints
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
## Handling Errors
|
|
40
|
+
|
|
41
|
+
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:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
curl --request POST \
|
|
45
|
+
--url http://localhost:8000/api/tables \
|
|
46
|
+
--header 'Content-Type: application/json' \
|
|
47
|
+
--data '{
|
|
48
|
+
"name": "Artist", # note that we already have an `artists` table
|
|
49
|
+
"schema": [
|
|
50
|
+
# ...
|
|
51
|
+
]
|
|
52
|
+
}'
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
```json
|
|
56
|
+
{
|
|
57
|
+
"message": "table artists already exists",
|
|
58
|
+
"error": {
|
|
59
|
+
"code": "SQLITE_ERROR"
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
```
|
|
@@ -0,0 +1,167 @@
|
|
|
1
|
+
# Extensions Examples
|
|
2
|
+
|
|
3
|
+
Soul extensions are a way to extend the functionality of Soul. Extensions are written in JavaScript and can be used to add new endpoints, modify existing endpoints, or add new functionality to Soul.
|
|
4
|
+
|
|
5
|
+
## Types of Extensions
|
|
6
|
+
|
|
7
|
+
- API Extensions: Add new endpoints to Soul
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
## Setup Environment
|
|
11
|
+
|
|
12
|
+
To follow the below examples we need to download a sample database and also install Soul CLI.
|
|
13
|
+
|
|
14
|
+
### Download Sample Database
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
wget https://raw.githubusercontent.com/lerocha/chinook-database/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite # Download sample sqlite database
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
### Using Soul CLI
|
|
21
|
+
```bash
|
|
22
|
+
npm install -g soul-cli
|
|
23
|
+
soul -d ./Chinook_Sqlite.sqlite -p 8000 -e "/absolute/path/to/_extensions/"
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
<details>
|
|
27
|
+
<summary>Or Using Local Development</summary>
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
git clone https://github.com/thevahidal/soul # Clone project
|
|
31
|
+
npm install # Install dependencies
|
|
32
|
+
npm link # might need `sudo`
|
|
33
|
+
soul -d ./Chinook_Sqlite.sqlite -p 8000 -e "/absolute/path/to/_extensions/"
|
|
34
|
+
```
|
|
35
|
+
</details>
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
## Creating an API extension
|
|
39
|
+
|
|
40
|
+
To create an extension, create a new folder named `_extensions`. Then create a file named `api.js` inside it. This file will contain the extension code.
|
|
41
|
+
|
|
42
|
+
```js
|
|
43
|
+
const hello = {
|
|
44
|
+
method: 'GET',
|
|
45
|
+
path: '/api/hello-soul',
|
|
46
|
+
handler: (req, res, db) => {
|
|
47
|
+
res.status(200).json({
|
|
48
|
+
message: 'Hello Soul!'
|
|
49
|
+
});
|
|
50
|
+
},
|
|
51
|
+
};
|
|
52
|
+
|
|
53
|
+
const timestamp = {
|
|
54
|
+
method: 'GET',
|
|
55
|
+
path: '/api/timestamp',
|
|
56
|
+
handler: (req, res, db) => {
|
|
57
|
+
res.status(200).json({
|
|
58
|
+
timestamp: Date.now(),
|
|
59
|
+
});
|
|
60
|
+
},
|
|
61
|
+
};
|
|
62
|
+
|
|
63
|
+
const greetings = {
|
|
64
|
+
method: 'POST',
|
|
65
|
+
path: '/api/greetings/:name',
|
|
66
|
+
handler: (req, res, db) => {
|
|
67
|
+
const { name } = req.params;
|
|
68
|
+
const { greeting } = req.body;
|
|
69
|
+
res.status(200).json({
|
|
70
|
+
message: `${greeting} ${name}!`,
|
|
71
|
+
});
|
|
72
|
+
},
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
const searchTables = {
|
|
76
|
+
method: 'GET',
|
|
77
|
+
path: '/api/search-tables',
|
|
78
|
+
handler: (req, res, db) => {
|
|
79
|
+
const { q } = req.query;
|
|
80
|
+
const sql = `
|
|
81
|
+
SELECT name FROM sqlite_master
|
|
82
|
+
WHERE type='table'
|
|
83
|
+
AND name LIKE $searchQuery
|
|
84
|
+
`;
|
|
85
|
+
try {
|
|
86
|
+
const tables = db.prepare(sql).all({
|
|
87
|
+
searchQuery: `%${q}%`,
|
|
88
|
+
});
|
|
89
|
+
res.status(200).json({
|
|
90
|
+
tables,
|
|
91
|
+
});
|
|
92
|
+
} catch (error) {
|
|
93
|
+
res.status(500).json({
|
|
94
|
+
error: error.message,
|
|
95
|
+
});
|
|
96
|
+
}
|
|
97
|
+
},
|
|
98
|
+
};
|
|
99
|
+
|
|
100
|
+
module.exports = {
|
|
101
|
+
hello,
|
|
102
|
+
timestamp,
|
|
103
|
+
greetings,
|
|
104
|
+
searchTables,
|
|
105
|
+
};
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Alright, now we can test if the extension is working:
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
curl http://localhost:8000/api/hello-soul
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
It should return:
|
|
116
|
+
|
|
117
|
+
```json
|
|
118
|
+
{
|
|
119
|
+
"message": "Hello Soul!"
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
And the same for the `timestamp` endpoint:
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
curl http://localhost:8000/api/timestamp
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
It should return:
|
|
130
|
+
|
|
131
|
+
```json
|
|
132
|
+
{
|
|
133
|
+
"timestamp": 1620000000000
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
And `greetings` endpoint:
|
|
138
|
+
|
|
139
|
+
```bash
|
|
140
|
+
curl -X POST -H "Content-Type: application/json" -d '{"greeting": "Hello"}' http://localhost:8000/api/greetings/John
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
It should return:
|
|
144
|
+
|
|
145
|
+
```json
|
|
146
|
+
{
|
|
147
|
+
"message": "Hello John!"
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
And `list-tables` endpoint:
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
curl http://localhost:8000/api/search-tables?q=al
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
It should return:
|
|
158
|
+
|
|
159
|
+
```json
|
|
160
|
+
{
|
|
161
|
+
"tables": [
|
|
162
|
+
{
|
|
163
|
+
"name": "Album"
|
|
164
|
+
}
|
|
165
|
+
]
|
|
166
|
+
}
|
|
167
|
+
```
|
package/docs/logo.png
ADDED
|
Binary file
|
|
Binary file
|