README.md

ClockAPI

ClockAPI is an ASP.NET Core Web API that calculates the angles of clock hands (hour and minute) based on user-provided time inputs. It also supports the reverse operation, calculating the time from given clock hand angles.

---

Features

1. Calculate Clock Hand Angles:

   • Given hours and minutes, the API calculates the angles of the hour and minute hands.
   • Input validation ensures hours are between 0 and 23, and minutes are between 0 and 59.

2. Calculate Time from Clock Hand Angles:

   • Given hour and minute angles, the API calculates the corresponding time.
   • Input validation ensures angles are between 0 and 359.

3. Swagger Documentation:

   • Automatically generates API documentation using Swagger.

4. Unit Testing:

   • Fully tested with unit tests to ensure reliability.

---

Project Structure

ClockAPI/
├── src/
│   └── ClockHandAPI/
│       ├── Controllers/
│       │   └── ClockController.cs          # API endpoints
│       ├── DTOs/
│       │   └── ClockHandsDto.cs            # Data Transfer Objects for input validation
│       ├── Models/
│       │   └── ClockHands.cs               # Domain models
│       ├── Services/
│       │   ├── ClockService.cs             # Business logic for calculating angles and time
│       │   └── IClockService.cs            # Interface for ClockService
│       ├── Program.cs                      # Entry point of the application
│       └── ClockHandAPI.csproj             # Project file
├── tests/
│   └── ClockHandAPI.Tests/
│       ├── ClockControllerTests.cs         # Tests for ClockController
│       ├── ClockHandsDtoTests.cs           # Tests for ClockHandsDto validation
│       ├── ClockServiceTests.cs            # Tests for ClockService
│       └── ClockHandAPI.Tests.csproj       # Test project file
├── ClockAPI.http                           # HTTP requests for testing the API
├── appsettings.json                        # Application configuration
├── appsettings.Development.json            # Development-specific configuration
├── Properties/
│   └── launchSettings.json                 # Configuration for launch profiles
└── README.md                               # Project documentation

---

How to Run

Prerequisites

• .NET 8 SDK
• An IDE (e.g., Visual Studio, Visual Studio Code, or JetBrains Rider)

Steps

1. Clone the Repository:

   git clone https://github.com/your-repo/ClockAPI.git
   cd ClockAPI

2. Restore Dependencies:

   dotnet restore

3. Run the Application:

   dotnet run --project src/ClockHandAPI/ClockHandAPI.csproj

4. Access Swagger UI:

   • Open your browser and navigate to https://localhost:5001/swagger (or http://localhost:5000/swagger).
   • Explore the API endpoints and test them interactively.

---

API Endpoints

1. Calculate Clock Hand Angles

• Endpoint: GET /api/clock/hands
• Query Parameters:
  • hours (int): The hour value (0–23).
  • minutes (int): The minute value (0–59).
• Example Request:

  GET /api/clock/hands?hours=12&minutes=30

• Example Response:

  {
    "hour": 195,
    "minute": 180
  }

2. Calculate Time from Clock Hand Angles

• Endpoint: GET /api/clock/time
• Query Parameters:
  • hourAngle (int): The hour hand angle (0–359).
  • minuteAngle (int): The minute hand angle (0–359).
• Example Request:

  GET /api/clock/time?hourAngle=195&minuteAngle=180

• Example Response:

  {
    "hours": 12,
    "minutes": 30
  }

---

Testing

Run Unit Tests

To run the unit tests, use the following command:

dotnet test tests/ClockHandAPI.Tests/ClockHandAPI.Tests.csproj

Test Coverage

• ClockController: Tests for valid and invalid inputs.
• ClockService: Tests for calculating angles and time.
• ClockHandsDto: Tests for input validation.

---

Technologies Used

• ASP.NET Core: For building the Web API.
• Swagger: For API documentation.
• xUnit: For unit testing.
• Moq: For mocking dependencies in unit tests.

---

Future Improvements

Use DTOs for the reverse operation endpoint to encapsulate input parameters.

---