docs(api): designed the basic vault endpoints

docs/README.md

@@ -4,11 +4,10 @@ Some API endpoints require an Authorization HTTP header.
 The token for this can be aquired using the `/account/authenticate` endpoint.
 
 ## 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`
     - [X] `/register`
@@ -32,8 +31,9 @@ The token for this can be aquired using the `/account/authenticate` endpoint.
     - [ ] `/info`
     - [ ] `/join`
 - `/vault`
-    - [ ] `/info` (ND)
+    - [ ] `/info`
-    - [ ] `/key` (ND)
+    - [ ] `/init`
+    - [ ] `/key`
     - `/fs`
         - [ ] `/create` (ND)
         - [ ] `/read` (ND)

docs/vault/info.md

@@ -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.

docs/vault/init.md

@@ -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.

docs/vault/key.md

@@ -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.