docs(readme): documented API and CLI

This commit is contained in:
antifallobst 2023-08-12 15:33:41 +02:00
parent 3832d15887
commit cc2e6080f4
Signed by: antifallobst
GPG Key ID: 2B4F402172791BAF
1 changed files with 59 additions and 0 deletions

View File

@ -1,3 +1,62 @@
# BaseAuth
Baseauth is a simple auth server, which is not meant to be usable in production environments.
---
# API
The API runs uses HTTP and runs by default on port `8080`.
All requests to endpoints are `POST`.
The _Content-Type_ is always `application/json`, so all payloads are JSON strings.
## endpoints
### `/register`
Registers a new account.
#### Content / Payload
| Field | Description |
|------------|-----------------------------------|
| `username` | The username of the account |
| `password` | The accounts' clear text password |
#### Responses
| Response | Description |
|----------|-----------------------------------------|
| 200 | User created successfully |
| 400 | Formal error in the request |
| 409 | The requested username is already in use |
| 500 | Internal server error |
### `/authenticate`
Authenticates using an existing account.
#### Payload
| Field | Description |
|------------|-----------------------------------|
| `username` | The username of the account |
| `password` | The accounts' clear text password |
#### Responses
| Response | Description |
|----------|---------------------------------------------------|
| 200 | Authenticated successfully |
| 400 | Formal error in the request |
| 401 | Authentication failure (wrong password) |
| 404 | There was no account found with the specified name |
| 500 | Internal server error |
---
# CLI
## Arguments
| Argument | Description |
|----------------------------|-----------------------------------------------------------------------------------------|
| `-D | --daemon` | Starts the server in daemon mode, to await api requests, etc. |
| `-d | --delete <username>` | Deletes the account associated with the specified username. |
| `-w | --dir <path>` | Specifies the working dir that will be used. This dir contains stuff like the database. |