docs(api): designed the basic vault endpoints

This commit is contained in:
antifallobst 2023-09-09 00:18:58 +02:00
parent 80460dfea3
commit d668a06431
Signed by: antifallobst
GPG Key ID: 2B4F402172791BAF
4 changed files with 111 additions and 7 deletions

View File

@ -4,11 +4,10 @@ Some API endpoints require an Authorization HTTP header.
The token for this can be aquired using the `/account/authenticate` endpoint. The token for this can be aquired using the `/account/authenticate` endpoint.
## Implementation Status ## Implementation Status
| Status | Explanation | Legend:
|--------|-------------------------------------| - [X] -> Implemented.
| [X] | Implemented and documented. | - [ ] -> Designed but not implemented yet.
| [ ] | Documented but not implemented yet. | - (ND) -> Not designed yet.
| (ND) | Not documented yet. |
- `/account` - `/account`
- [X] `/register` - [X] `/register`
@ -32,8 +31,9 @@ The token for this can be aquired using the `/account/authenticate` endpoint.
- [ ] `/info` - [ ] `/info`
- [ ] `/join` - [ ] `/join`
- `/vault` - `/vault`
- [ ] `/info` (ND) - [ ] `/info`
- [ ] `/key` (ND) - [ ] `/init`
- [ ] `/key`
- `/fs` - `/fs`
- [ ] `/create` (ND) - [ ] `/create` (ND)
- [ ] `/read` (ND) - [ ] `/read` (ND)

25
docs/vault/info.md Normal file
View File

@ -0,0 +1,25 @@
# `/vault/info` - GET
Returns status information about the vault.
## HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
## Responses
### 200 - Success
__Content - JSON:__
| Field | Description |
|--------------|--------------------------------------------|
| max_storage | The maximum amount of space in the vault. |
| free_storage | The amount of free space in the vault. |
### 400 - Error: Bad Request
The request was malformed.
### 401 - Error: Unauthorized
The provided auth token doesn't allow you to perform this operation.
### 403 - Error: Forbidden
Blocked for security reasons.
### 404 - Error: Not Found
The authorized user has no vault.
This can be fixed with a `/vault/init` call.

28
docs/vault/init.md Normal file
View File

@ -0,0 +1,28 @@
# `/vault/init` - POST
Sets up a vault for the authenticated user.
## HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
| Content-Type | `application/json` |
## Content - JSON
| Field | Description |
|-------|-----------------------------------------|
| key | The encrypted ContentKey for the vault. |
## Responses
### 200 - Success
Successfully set up the vault.
### 208 - Already Reported
The authenticated user already has a vault.
### 400 - Error: Bad Request
The request was malformed.
### 401 - Error: Unauthorized
The provided auth token doesn't allow you to perform this operation.
### 403 - Error: Forbidden
Blocked for security reasons.

51
docs/vault/key.md Normal file
View File

@ -0,0 +1,51 @@
# `/vault/key` - GET
Returns the encrypted ContentKey of the vault.
## HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
## Responses
### 200 - Success
__Content - JSON:__
| Field | Description |
|-------|----------------------------------|
| key | The vaults encrypted ContentKey. |
### 401 - Error: Unauthorized
The provided auth token doesn't allow you to perform this operation.
### 403 - Error: Forbidden
Blocked for security reasons.
### 404 - Error: Not Found
The authorized user has no vault.
This can be fixed with a `/vault/init` call.
# `/vault/key` - PUSH
Uploads a new encrypted ContentKey and with this replacing the old one.
This should __never__ change the ContentKey itself but only the encryption layer around it.
This is intended to be used for password changing only!
## HTTP Headers
| Header | Content |
|---------------|--------------------|
| Authorization | `Bearer {token}` |
| Content-Type | `application/json` |
## Content - JSON
| Field | Description |
|-------|----------------------------------|
| key | The vaults encrypted ContentKey. |
## Responses
### 200 - Success
Changed the encrypted ContentKey successfully.
### 400 - Error: Bad Request
The request was malformed.
### 401 - Error: Unauthorized
The provided auth token doesn't allow you to perform this operation.
### 403 - Error: Forbidden
Blocked for security reasons.
### 404 - Error: Not Found
The authorized user has no vault.
This can be fixed with a `/vault/init` call.