Added documentation

LotuxPunk · Jun 1, 2024 · 52a6e0e · 52a6e0e
1 parent 1ca568d
commit 52a6e0e
Showing 1 changed file with 128 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -8,3 +8,131 @@ This project intends to be a reliable and simple solution for small scale file m
 
 - Inter-server communication, since it's an api key based authentication, the key should be kept secret and not exposed to the client side.
 - It is intended to be used with small/constrained file sizes, the file you'll try to manipulate will be loaded into memory and then sent to the server. For large files, it's recommended to use a more robust solution like [AWS S3](https://aws.amazon.com/s3/), [Google Cloud Storage](https://cloud.google.com/storage) or [Azure Blob Storage](https://azure.microsoft.com/en-us/services/storage/blobs/).
+
+## 1. Environment Variables
+
+To run this project, you will need to add the following environment variables:
+- `API_KEY`, a random secret key that will be used to authenticate the requests.
+- `BASE_DIRECTORY`, the base directory where the files will be stored.
+
+## 2. Documentation
+
+### 2.1. Endpoints
+
+#### 2.1.1. Authorization
+
+All requests must have the `Authorization` header with the value of a one-time-token generated by the server.
+
+Since the API key is a secret, it should not be exposed to the client side, so the server will generate a one-time-token that will be used to authenticate the requests.
+
+[![](https://mermaid.ink/img/pako:eNpVj70OwjAMhF8l8gSiVcWaoQMCxMZAxyxWY9qqJIE0QUJV3x33D4kMkZ377uz0UDpNIKGjVyRb0rHByqNRVvA5e2fDyeo0z3cHLFsupfAj2QXhLKWhMXy5lqzYXItiO9sWdHRdmGxQiuy9zzCGOpvgGZu1lLH0F84h_xmjuq4xyZCAIW-w0bx1P8IKQk2GFEguNfpWgbIDczzQ3T62BBl8pAS8i1UN8o6Pjrv41BjW_y6vwxcYFVjX?type=png)](https://mermaid.live/edit#pako:eNpVj70OwjAMhF8l8gSiVcWaoQMCxMZAxyxWY9qqJIE0QUJV3x33D4kMkZ377uz0UDpNIKGjVyRb0rHByqNRVvA5e2fDyeo0z3cHLFsupfAj2QXhLKWhMXy5lqzYXItiO9sWdHRdmGxQiuy9zzCGOpvgGZu1lLH0F84h_xmjuq4xyZCAIW-w0bx1P8IKQk2GFEguNfpWgbIDczzQ3T62BBl8pAS8i1UN8o6Pjrv41BjW_y6vwxcYFVjX)
+
+##### GET `/v1/auth/token`
+
+Generates a one-time-token that will be used to authenticate the requests.
+
+###### Query Parameters
+
+| Name       | Type     | Description                                    |
+|------------|----------|------------------------------------------------|
+| `fileName` | `string` | The name of the file that will be manipulated. |
+| `path`     | `string` | The path of the file that will be manipulated. |
+
+###### Headers
+
+| Name            | Type     | Description         |
+|-----------------|----------|---------------------|
+| `Authorization` | `string` | The API key.        |
+| `Content-Type`  | `string` | `application/json`. |
+| `Accept`        | `string` | `application/json`. |
+
+###### Response
+
+    ```json
+    {
+        "token": "...",
+    }
+    ```
+
+> :warning: **Token expiration time**: 5 minutes.
+
+#### 2.1.2. File Manipulation
+
+##### POST `/v1/file`
+
+Uploads a file to the server.
+
+###### Headers
+
+| Name            | Type     | Description         |
+|-----------------|----------|---------------------|
+| `Authorization` | `string` | The one-time-token. |
+| `Content-Type`  | `string` | `application/json`. |
+| `Accept`        | `string` | `application/json`. |
+
+###### Request Body
+
+    ```json
+    {
+        "fileName": "example.txt",
+        "path": "/",
+        "file": "base64-encoded-file"
+    }
+    ```
+
+##### GET `/v1/file`
+
+Downloads a file from the server.
+
+###### Query Parameters
+
+| Name       | Type     | Description                                   |
+|------------|----------|-----------------------------------------------|
+| `fileName` | `string` | The name of the file that will be downloaded. |
+| `path`     | `string` | The path of the file that will be downloaded. |
+
+###### Headers
+
+| Name            | Type     | Description                                      |
+|-----------------|----------|--------------------------------------------------|
+| `Authorization` | `string` | The one-time-token.                              |
+| `Content-Type`  | `string` | `application/json`.                              |
+| `Accept`        | `string` | `application/json` or `application/octet-stream` |
+
+###### Response
+
+If the `Accept` header is `application/json`:
+
+    ```json
+    {
+        "fileName": "example.txt",
+        "path": "/",
+        "file": "base64-encoded-file"
+    }
+    ```
+
+If the `Accept` header is `application/octet-stream`: stream the file.
+
+##### DELETE `/v1/file`
+
+Deletes a file from the server.
+
+###### Query Parameters
+
+| Name        | Type      | Description                                |
+|-------------|-----------|--------------------------------------------|
+| `fileName`  | `string`  | The name of the file that will be deleted. |
+| `path`      | `string`  | The path of the file that will be deleted. |
+| `recursive` | `boolean` | If `true`, deletes all files in the path.  |
+
+`path` is required, but `fileName` is optional. If `fileName` is not provided, it'll try to delete the whole path specified in `path`
+
+`recursive` is optional, if `true`, it'll delete recursively all files in the path. (even nested directories)
+
+###### Headers
+
+| Name            | Type     | Description         |
+|-----------------|----------|---------------------|
+| `Authorization` | `string` | The one-time-token. |
+| `Content-Type`  | `string` | `application/json`. |
+| `Accept`        | `string` | `application/json`. |