|
# retoor <retoor@molodetz.nl>
|
|
|
|
# typosaurus-sandbox
|
|
|
|
Sandbox for Typosaurus end-to-end verification.
|
|
|
|
A FastAPI application serving arithmetic operations over HTTP with JSON request/response bodies.
|
|
|
|
## Configuration
|
|
|
|
The application uses a single `.env.json` file at the project root as its central point of truth
|
|
for configuration. Defaults are plug-and-play and require no setup:
|
|
|
|
```json
|
|
{
|
|
"host": "127.0.0.1",
|
|
"port": 8000
|
|
}
|
|
```
|
|
|
|
When no `.env.json` is present, the application starts with these defaults. To customise, create
|
|
`.env.json` in the project root and populate only the keys that differ.
|
|
|
|
## Usage
|
|
|
|
### Start the server
|
|
|
|
```sh
|
|
python -m typosaurus_sandbox
|
|
```
|
|
|
|
The server listens on `http://127.0.0.1:8000` by default.
|
|
|
|
### Health check
|
|
|
|
```
|
|
GET /health
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{"status": "ok"}
|
|
```
|
|
|
|
## API endpoints
|
|
|
|
All calculator endpoints accept `POST` requests with a JSON body and return a JSON response.
|
|
|
|
### POST /api/v1/calculator/add
|
|
|
|
Add two integers.
|
|
|
|
Request:
|
|
|
|
```json
|
|
{"left": 3, "right": 5}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{"result": 8}
|
|
```
|
|
|
|
### POST /api/v1/calculator/subtract
|
|
|
|
Subtract the right integer from the left.
|
|
|
|
Request:
|
|
|
|
```json
|
|
{"left": 10, "right": 3}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{"result": 7}
|
|
```
|
|
|
|
### POST /api/v1/calculator/clamp
|
|
|
|
Clamp a value between a low and high bound.
|
|
|
|
Request:
|
|
|
|
```json
|
|
{"value": 15, "low": 0, "high": 10}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{"result": 10}
|
|
```
|
|
|
|
Boundaries are inclusive. A `low > high` combination produces a 422 validation response.
|
|
|
|
### POST /api/v1/calculator/clamp-to-byte
|
|
|
|
Clamp an integer to the byte range [0, 255].
|
|
|
|
Request:
|
|
|
|
```json
|
|
{"value": 300}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{"result": 255}
|
|
```
|
|
|
|
### POST /api/v1/calculator/average
|
|
|
|
Compute the arithmetic mean of a list of values.
|
|
|
|
Request:
|
|
|
|
```json
|
|
{"values": [1, 2, 3, 4, 5]}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{"result": 3.0}
|
|
```
|
|
|
|
An empty list produces a 422 validation response.
|
|
|
|
### POST /api/v1/calculator/median
|
|
|
|
Compute the median of a list of values. Values are sorted internally; an even-length list returns the average of the two middle values as a float.
|
|
|
|
Request:
|
|
|
|
```json
|
|
{"values": [1, 3, 5]}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{"result": 3.0}
|
|
```
|
|
|
|
Request (even length):
|
|
|
|
```json
|
|
{"values": [1, 2, 3, 4]}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{"result": 2.5}
|
|
```
|
|
|
|
An empty list produces a 422 validation response.
|
|
|
|
### POST /api/v1/calculator/variance
|
|
|
|
Compute the population variance of a list of values.
|
|
|
|
Request:
|
|
|
|
```json
|
|
{"values": [1, 2, 3, 4, 5]}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{"result": 2.0}
|
|
```
|
|
|
|
An empty list produces a 422 validation response.
|
|
|
|
### POST /api/v1/calculator/percentage
|
|
|
|
Compute what percentage `value` is of `total`.
|
|
|
|
Request:
|
|
|
|
```json
|
|
{"value": 50, "total": 100}
|
|
```
|
|
|
|
Response:
|
|
|
|
```json
|
|
{"result": 50.0}
|
|
```
|
|
|
|
A zero `total` produces a 422 validation response.
|
|
|
|
## Verification
|
|
|
|
```sh
|
|
make verify
|
|
```
|
|
|
|
Runs compile-all checks against all source and test files, then executes the full test suite.
|
|
Zero warnings are tolerated.
|
|
|