146 أسطر
3.8 KiB
Markdown
146 أسطر
3.8 KiB
Markdown
# WondersAPI 🏛️
|
|
|
|
A RESTful API built with ASP.NET Core to manage a collection of historical wonders. It provides full CRUD (Create, Read, Update, Delete) functionality and an endpoint to fetch a random wonder from the database.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- List all wonders
|
|
- Get a specific wonder by ID
|
|
- Get a random wonder
|
|
- Create, Update, Delete operations
|
|
- Structured logging and a small set of helper scripts for monitoring and testing
|
|
|
|
---
|
|
|
|
## Quick start
|
|
|
|
From the project root (where `Ghaymah.WondersAPI.csproj` lives) you can run the API with the .NET SDK or inside Docker.
|
|
|
|
Run with the .NET SDK (requires .NET 8 SDK):
|
|
|
|
```bash
|
|
dotnet run
|
|
```
|
|
|
|
Run inside Docker (uses the .NET 8 SDK image, maps container port 5004 to host 5004):
|
|
|
|
```bash
|
|
docker run -it --rm -p 5004:5004 -v "$(pwd):/app" -w /app mcr.microsoft.com/dotnet/sdk:8.0 dotnet run
|
|
```
|
|
|
|
PowerShell note: if `$(pwd)` doesn't work in your environment, use `${PWD}` or the absolute path, for example:
|
|
|
|
```powershell
|
|
docker run -it --rm -p 5004:5004 -v "${PWD}:/app" -w /app mcr.microsoft.com/dotnet/sdk:8.0 dotnet run
|
|
```
|
|
|
|
## Scripts
|
|
|
|
This repository includes two helper scripts used during development and testing:
|
|
|
|
- `monitor.sh` — simple monitor script that forwards events to a monitoring endpoint
|
|
- `test_api.sh` — basic API test runner that consumes `test_cases.json`
|
|
|
|
### monitor.sh
|
|
|
|
Usage:
|
|
|
|
```bash
|
|
./monitor.sh <ghaymah-monitoring-endpoint-url>
|
|
```
|
|
|
|
Example:
|
|
|
|
```bash
|
|
./monitor.sh https://example.com/ingest
|
|
```
|
|
|
|
On Windows, run `monitor.sh` from WSL, Git Bash, or adapt it to PowerShell (e.g., use `Invoke-RestMethod`).
|
|
|
|
### test_api.sh
|
|
|
|
Usage (POSIX shells / Git Bash / WSL):
|
|
|
|
```bash
|
|
BASE_URL='http://localhost:5004' ./test_api.sh test_cases.json
|
|
```
|
|
|
|
PowerShell examples:
|
|
|
|
Set environment variable for the session and run the script:
|
|
|
|
```powershell
|
|
$env:BASE_URL = 'http://localhost:5004'
|
|
./test_api.sh test_cases.json
|
|
```
|
|
|
|
Or invoke using bash from PowerShell if the script requires bash:
|
|
|
|
```powershell
|
|
bash -c "BASE_URL='http://localhost:5004' ./test_api.sh test_cases.json"
|
|
```
|
|
|
|
## API Documentation (Swagger)
|
|
|
|
When the API is running the Swagger UI is available at:
|
|
|
|
```
|
|
http://localhost:5004/docs
|
|
```
|
|
|
|
If your launch configuration or production mapping differs, adjust the host and port accordingly.
|
|
|
|
## Endpoints
|
|
|
|
Base route: `/api/wonders`
|
|
|
|
- GET /api/wonders — list all wonders
|
|
- GET /api/wonders/{id} — get a wonder by id
|
|
- POST /api/wonders — create a new wonder
|
|
- PUT /api/wonders/{id} — update a wonder
|
|
- DELETE /api/wonders/{id} — delete a wonder
|
|
- GET /api/wonders/random — get a random wonder
|
|
|
|
Example create request:
|
|
|
|
```json
|
|
{
|
|
"name": "Great Pyramid of Giza",
|
|
"country": "Egypt",
|
|
"era": "Ancient",
|
|
"type": "Tomb",
|
|
"description": "The oldest and largest of the three pyramids in the Giza pyramid complex.",
|
|
"discoveryYear": -2560
|
|
}
|
|
```
|
|
|
|
## Included files
|
|
|
|
- `monitor.sh` — monitoring helper script
|
|
- `test_api.sh` — test runner script
|
|
- `test_cases.json` — test definitions used by `test_api.sh`
|
|
- `seed-data.json` — sample data used for seeding
|
|
- `appsettings.json` / `appsettings.Development.json` — configuration files
|
|
|
|
## Logs
|
|
|
|
Log files are output to the `Logs/` folder (e.g. `Logs/api.log`) as configured in `appsettings.json`.
|
|
|
|
## GitPasha repository URL
|
|
|
|
Replace the placeholder with your repository URL hosted on GitPasha:
|
|
|
|
https://gitpasha.example.com/your-username/ghaymah-log-monitoring-project
|
|
|
|
## Troubleshooting
|
|
|
|
- If `dotnet run` fails, confirm .NET 8 SDK is installed: `dotnet --list-sdks`.
|
|
- If Docker fails, ensure Docker Desktop is running and the mounted path is available in Docker.
|
|
- On Windows, use WSL or Git Bash for shell scripts, or convert scripts to PowerShell.
|
|
|
|
## License
|
|
|
|
Add your license here.
|