From 2c951fd83491c65c75141c9dd338b120d3aec677 Mon Sep 17 00:00:00 2001 From: sjdonado Date: Tue, 18 Mar 2025 11:23:28 +0100 Subject: [PATCH] chore: update API.md response status codes --- README.md | 5 ++- docs/API.md | 6 +++ docs/SETUP.md | 118 +++++++++++++++++++++++++++++++++++++++++++------- 3 files changed, 112 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 70f7f47..f6499a4 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,10 @@ Lightweight URL shortener API service with minimal resource requirements. Average memory consumption is under **20MiB** and single CPU core consumption under 20%. -bit is highly performant, achieving maximum **5K RPS** with a minimum latency of 64ms (100K requests using 100 connections, [benchmark](docs/SETUP.md#benchmark)). +bit is highly performant, achieving maximum **3K RPS** with a minimum latency of 56ms (100K requests using 100 connections, [benchmark](docs/SETUP.md#benchmark)). + +Self-hosted with [Dokku](docs/SETUP.md#dokku) and [Docker Compose](docs/SETUP.md#docker-compose). -Self-hosted with [Dokku](docs/SETUP.md#dokku) and [Docker Compose](SETUP.md#docker-compose). Images available on [Docker Hub](https://hub.docker.com/r/sjdonado/bit/tags). ## Why bit? diff --git a/docs/API.md b/docs/API.md index 2b0a6e4..83a54fd 100644 --- a/docs/API.md +++ b/docs/API.md @@ -4,6 +4,7 @@ - Endpoint: `GET /api/ping` - Payload: None + - Response: 200 - Response Example ```json { @@ -23,6 +24,7 @@ - Query Parameters: - `limit` (optional): Number of results per page (default: 100) - `cursor` (optional): Pagination cursor from previous response + - Response: 200 - Response Example ```json { @@ -45,6 +47,7 @@ - Headers: `X-Api-Key` - Payload: None - Note: This endpoint returns up to 100 of the most recent clicks. For complete click history, use the `/api/links/:id/clicks` endpoint with pagination. + - Response: 200 - Response Example ```json { @@ -73,6 +76,7 @@ - Query Parameters: - `limit` (optional): Number of results per page (default: 100) - `cursor` (optional): Pagination cursor from previous response + - Response: 200 - Response Example ```json { @@ -103,6 +107,7 @@ } ``` - Headers: `X-Api-Key` + - Response: 201 - Response Example: ```json { @@ -124,6 +129,7 @@ } ``` - Headers: `X-Api-Key` + - Response: 200 - Response Example: ```json { diff --git a/docs/SETUP.md b/docs/SETUP.md index 07e3c46..82519e2 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -11,7 +11,7 @@ Options: ## Run It Anywhere -### docker-compose +### Docker Compose ```bash docker-compose up @@ -109,29 +109,35 @@ ENV=test crystal spec ## Benchmark +RAM: 1GiB CPU: Apple M3 Pro +**Summary** +- Requests/secs average central tendency: (1328.47 + 1357.19 + 1407.03) / 3 + (1785.03 + 1789.06 + 1778.84) / 3 = 3148.54 reqs/sec +- Latency average central tendency: (76.19 + 74.68 + 71.85) / 3 - (29.43 + 14.50 + 9.42) / 3 = 56.4ms +- Latency for conservative capacity planning: (76.19 + 74.68 + 71.85) / 3 + (29.43 + 14.50 + 9.42) / 3 = 89.63ms +- Best Single Run: 18041.44 reqs/sec + ``` -> colima start --cpu 1 --memory 1 +~/p/bit> colima start --cpu 1 --memory 1 INFO[0000] starting colima INFO[0000] runtime: docker INFO[0001] starting ... context=vm INFO[0076] provisioning ... context=docker INFO[0077] starting ... context=docker INFO[0077] done - -> ./benchmark.sh +~/p/bit> ./benchmark.sh Setting up... [+] Running 3/3 ✔ Network bit_default Created 0.0s ✔ Volume "bit_sqlite_data" Created 0.0s ✔ Container bit Started 0.1s -Captured API Key: W-m-NkAqcMXQjdq9fNu3Ig +Captured API Key: xFWMNJndUzuAC5sSRqgbSA Waiting for the application to be ready... HTTP/1.1 200 OK Connection: keep-alive Content-Type: application/json -Date: Tue, 18 Mar 2025 06:48:32 GMT +Date: Tue, 18 Mar 2025 10:04:32 GMT Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS Access-Control-Allow-Headers: Content-Type, Accept, Origin, X-Api-Key @@ -141,24 +147,106 @@ Starting resource usage monitoring... Creating 10000 short links with 100 concurrent requests... Link creation complete: 10000 links created using httpbin's anything endpoint. Fetching all created links from /api/links... -Selected link for benchmarking: http://localhost:4000/xkCfyw +Selected link for benchmarking: http://localhost:4000/4NRtcA Starting benchmark with Bombardier... -Bombarding http://localhost:4000/xkCfyw with 100000 request(s) using 100 connection(s) - 100000 / 100000 [=============================================================] 100.00% 1466/s 1m8s +Bombarding http://localhost:4000/4NRtcA with 100000 request(s) using 100 connection(s) + 100000 / 100000 [============================================================] 100.00% 1308/s 1m16s Done! Statistics Avg Stdev Max - Reqs/sec 1486.25 1813.58 5332.24 - Latency 68.01ms 4.74ms 92.22ms + Reqs/sec 1328.47 1785.03 10390.15 + Latency 76.19ms 29.43ms 702.17ms HTTP codes: 1xx - 0, 2xx - 0, 3xx - 100000, 4xx - 0, 5xx - 0 others - 0 - Throughput: 631.71KB/s + Throughput: 563.57KB/s Benchmark completed. Analyzing resource usage... **** Results **** -Average CPU Usage: 39.77% -Average Memory Usage: 35.90 MiB -./benchmark.sh: line 135: 86037 Terminated: 15 monitor_resource_usage +Average CPU Usage: 37.02% +Average Memory Usage: 31.78 MiB +./benchmark.sh: line 135: 44688 Terminated: 15 monitor_resource_usage +[+] Running 2/2 + ✔ Container bit Removed 10.1s + ✔ Network bit_default Removed 0.0s +~/p/bit> ./benchmark.sh +Setting up... +[+] Running 2/2 + ✔ Network bit_default Created 0.0s + ✔ Container bit Started 0.1s +Captured API Key: zmEqrjCMbOGzdOXoCZPPsw +Waiting for the application to be ready... +HTTP/1.1 200 OK +Connection: keep-alive +Content-Type: application/json +Date: Tue, 18 Mar 2025 10:07:11 GMT +Access-Control-Allow-Origin: * +Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS +Access-Control-Allow-Headers: Content-Type, Accept, Origin, X-Api-Key +Content-Length: 13 + +Starting resource usage monitoring... +Creating 10000 short links with 100 concurrent requests... +Link creation complete: 10000 links created using httpbin's anything endpoint. +Fetching all created links from /api/links... +Selected link for benchmarking: http://localhost:4000/kai6VA +Starting benchmark with Bombardier... +Bombarding http://localhost:4000/kai6VA with 100000 request(s) using 100 connection(s) + 100000 / 100000 [============================================================] 100.00% 1336/s 1m14s +Done! +Statistics Avg Stdev Max + Reqs/sec 1357.19 1789.06 18041.44 + Latency 74.68ms 14.50ms 304.69ms + HTTP codes: + 1xx - 0, 2xx - 0, 3xx - 100000, 4xx - 0, 5xx - 0 + others - 0 + Throughput: 575.03KB/s +Benchmark completed. +Analyzing resource usage... +**** Results **** +Average CPU Usage: 38.00% +Average Memory Usage: 30.75 MiB +./benchmark.sh: line 135: 64339 Terminated: 15 monitor_resource_usage +[+] Running 2/2 + ✔ Container bit Removed 10.1s + ✔ Network bit_default Removed 0.0s +~/p/bit> ./benchmark.sh +Setting up... +[+] Running 2/2 + ✔ Network bit_default Created 0.0s + ✔ Container bit Started 0.1s +Captured API Key: fObPw7vIDCFBaxr8e9bI8g +Waiting for the application to be ready... +HTTP/1.1 200 OK +Connection: keep-alive +Content-Type: application/json +Date: Tue, 18 Mar 2025 10:08:57 GMT +Access-Control-Allow-Origin: * +Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS +Access-Control-Allow-Headers: Content-Type, Accept, Origin, X-Api-Key +Content-Length: 13 + +Starting resource usage monitoring... +Creating 10000 short links with 100 concurrent requests... +Link creation complete: 10000 links created using httpbin's anything endpoint. +Fetching all created links from /api/links... +Selected link for benchmarking: http://localhost:4000/oxmHow +Starting benchmark with Bombardier... +Bombarding http://localhost:4000/oxmHow with 100000 request(s) using 100 connection(s) + 100000 / 100000 [============================================================] 100.00% 1388/s 1m12s +Done! +Statistics Avg Stdev Max + Reqs/sec 1407.03 1778.84 5866.74 + Latency 71.85ms 9.42ms 175.45ms + HTTP codes: + 1xx - 0, 2xx - 0, 3xx - 100000, 4xx - 0, 5xx - 0 + others - 0 + Throughput: 597.97KB/s +Benchmark completed. +Analyzing resource usage... +**** Results **** +Average CPU Usage: 38.49% +Average Memory Usage: 36.48 MiB +./benchmark.sh: line 135: 79562 Terminated: 15 monitor_resource_usage [+] Running 2/2 ✔ Container bit Removed 10.1s ✔ Network bit_default Removed 0.0s