Add examples for Rows endpoint in auth mode

README.md

@@ -68,16 +68,16 @@ Run the Soul command with the necessary parameters:
 
 ```
 
-Note: When configuring your JWT Secret, it is recommended to use a long string value for enhanced security. It is advisable to use a secret that is at least 10 characters in length.
+> Note: When configuring your JWT Secret, it is recommended to use a long string value for enhanced security. It is advisable to use a secret that is at least 10 characters in length.
 
 In this example:
 
-The `-a` flag instructs Soul to run in auth mode.
+- The `-a` flag instructs Soul to run in auth mode.
-The `--ts` flag allows you to pass a JWT secret value for the `access and refresh tokens` generation and verification. Replace <your_jwt_secret_value> with your desired secret value.
+- The `--ts` flag allows you to pass a JWT secret value for the `access and refresh tokens` generation and verification. Replace <your_jwt_secret_value> with your desired secret value.
-The `--atet` flag sets the JWT expiration time for the access token. In this case, it is set to four hours (4H), meaning the token will expire after 4 hours.
+- The `--atet` flag sets the JWT expiration time for the access token. In this case, it is set to four hours (4H), meaning the token will expire after 4 hours.
-The `--rtet` flag sets the JWT expiration time for the refresh token. In this case, it is set to three days (3D), meaning the token will expire after 3 days.
+- The `--rtet` flag sets the JWT expiration time for the refresh token. In this case, it is set to three days (3D), meaning the token will expire after 3 days.
-The `--iuu` flag is used to pass a username for the initial user
+- The `--iuu` flag is used to pass a username for the initial user
-The `--iup` flag is used to pass a password for the initial user
+- The `--iup` flag is used to pass a password for the initial user
 
 Here are some example values for the `atet` and `rtet` flags
 

docs/api-examples.md

@@ -33,9 +33,10 @@ soul -d ./Chinook_Sqlite.sqlite -p 8000
 
 ## Namespaces
 
-1. [/api/tables](api/tables-examples.md) Examples for Tables endpoints
+1. [/api/tables/](api/tables-examples.md) Examples for Tables endpoints
-2. [/api/rows](api/rows-examples.md) Examples for Rows 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

docs/api/rows-auth-examples.md

@@ -0,0 +1,139 @@
+## Rows in Auth mode
+
+### 1. List Rows of a Table in Auth mode
+
+To list rows in auth mode we call `/tables/<table-name>/rows/` endpoint with `GET` method and pass the jwt access token via Cookies.
+
+> Note that your account needs to have access to read this table.
+> Access (Authorization) in Soul is handled via "\_roles" table aka Roles.
+> If you want to learn about granting permissions proceed to the next example.
+
+```bash
+curl 'localhost:8000/api/tables/Album/rows/' \
+  --cookie 'accessToken=<jwt-access-token>'
+```
+
+Response
+
+```json
+{
+  "data": [
+    {
+      "AlbumId": 1,
+      "Title": "For Those About To Rock We Salute You",
+      "ArtistId": 1
+    },
+    { "AlbumId": 2, "Title": "Balls to the Wall", "ArtistId": 2 }
+    // ...
+  ],
+  "total": 347,
+  "next": "/tables/Album?page=2",
+  "previous": null
+}
+```
+
+#### Cookies
+
+- `accessToken` the access token that you acquired before
+
+### 2. Granting access to users
+
+Only super users (e.g. `is_superuser=true`) or those who got roles that have access to '\_roles' table, can grant access to other users.
+
+> Head over to [README](/README.md) and _Updating Super Users_ section to learn how to promote someone to a super user.
+
+#### 2.1. Create a new Role
+
+To create a new Role call `/tables/_roles/rows/` endpoint with `POST` method.
+
+```bash
+curl --request POST \
+  --url http://localhost:8000/api/tables/_roles/rows/ \
+  --header 'Content-Type: application/json' \
+  --header 'Cookie: accessToken=<jwt-access-token>' \
+  --data '{
+  "fields": {
+    "name": "editor"
+  }
+}'
+```
+
+Response
+
+```json
+{
+  "message": "Row inserted",
+  "data": {
+    "changes": 1,
+    "lastInsertRowid": 2
+  }
+}
+```
+
+Now that we have our `editor` Role, we can give it some permissions. Here we want to give it permission to `read` `Album` table.
+
+#### 2.2. Create permissions for a Role
+
+To create permissions for a Role call `/tables/_roles_permissions/rows/` endpoint with `POST` method.
+
+```bash
+curl --request POST \
+  --url http://localhost:8000/api/tables/_roles_permissions/rows/ \
+  --header 'Content-Type: application/json' \
+  --header 'Cookie: <jwt-access-token>' \
+  --data '{
+  "fields": {
+    "role_id": 2,
+    "table_name": "Album",
+    "create": 0,
+    "read": 1,
+    "update": 0,
+    "delete": 0
+  }
+}'
+```
+
+Response
+
+```json
+{
+  "message": "Row inserted",
+  "data": {
+    "changes": 1,
+    "lastInsertRowid": 6
+  }
+}
+```
+
+Oh, now that we created the Role Permission think that it's better for `editor` role to have both `read` and `create` permissions.
+
+#### 2.3. Assign Role to a User
+
+To assign roles to a user call `/tables/_users_roles/rows/` endpoint with `POST` method.
+
+```bash
+curl --request POST \
+  --url http://localhost:8000/api/tables/_users_roles/rows/ \
+  --header 'Content-Type: application/json' \
+  --header 'Cookie: <jwt-access-token>' \
+  --data '{
+  "fields": {
+    "user_id": 1,
+    "role_id": 2
+  }
+}'
+```
+
+Response
+
+```json
+{
+  "message": "Row inserted",
+  "data": {
+    "changes": 1,
+    "lastInsertRowid": 2
+  }
+}
+```
+
+Now that we assigned `editor` role to a user, he / she can read the `Album` table.