docs: API documentation section for world-clockify (#15)

 Created API Integration section to document all available endpoints

- Fetch Current Time API
- Fetch Supported Timezones API
- Fetch Converted Time API
- Fetch Time Difference API
- Calculate Duration API
- Format Date in Timezone API

Enhances the usability of the API for developers by providing clear examples and usage instructions.

docs/_sidebar.md

@@ -6,7 +6,7 @@
 
 </details>
 
-<details  open style="margin-left: 20px">
+<details  open  style="margin-left: 20px">
 <summary>How to Use</summary>
 
 - [Get Current Time in Zone](./guide/getCurrentTimeInZone.md)
@@ -17,3 +17,16 @@
 - [Calculate Duration](./guide/calculateDuration.md)
 
 </details>
+
+<details open style="margin-left: 20px">
+<summary>API Integration</summary>
+
+- [API Overview](./api/Introduction.md)
+- [Fetch Current Time API](./api/fetchCurrentTime.md)
+- [Fetch Supported Timezones API](./api/fetchSupportedTimezones.md)
+- [Fetch Converted Time API](./api/fetchConvertedTime.md)
+- [Fetch Time Difference API](./api/fetchTimeDifference.md)
+- [Calculate Duration API](./api/calculateDurationAPI.md)
+- [Format Date in Timezone API](./api/formatDateInTimezoneAPI.md)
+
+</details>

docs/api/Introduction.md

@@ -0,0 +1,43 @@
+Let’s explore why a user might prefer to use the API endpoints instead of installing your world-clockify NPM package. While both options offer timezone and date manipulation features, there are several distinct use cases where the API might be a better fit:
+
+## Note
+
+Our base URl for the API is `https://world-clockify.com/api/v1/` and all the endpoints are relative to this base URL.
+
+## 1. Serverless/Lightweight Client Applications
+
+When to Use the API: For applications that run in environments where installing Node.js packages is not feasible, such as serverless environments (AWS Lambda, Cloudflare Workers), lightweight web applications, or frontend-only applications.
+Why: The API allows developers to make simple HTTP requests from the client-side (browser) without bundling additional dependencies.
+
+- Example: A static website that needs to display current times across various timezones but wants to avoid increasing the bundle size by installing the world-clockify package.
+
+## 2. Cross-Platform & Language-Agnostic Integration
+
+When to Use the API: Developers working in languages other than JavaScript/TypeScript (e.g., Python, Ruby, Java) who need timezone and date operations.
+Why: The API can be called from any environment that supports HTTP requests, making it accessible across different platforms and programming languages.
+Example: A Python backend or mobile app in Swift/Java that needs to calculate time differences but can't directly use the NPM package.
+
+## 3. Low-Resource or Minimal Infrastructure
+
+When to Use the API: Developers who are working on a project that doesn’t require full control over the logic or heavy infrastructure (e.g., serverless apps or lightweight microservices).
+Why: By using the API, developers can delegate the heavy lifting of timezone management to your backend, reducing local resource consumption (e.g., memory, CPU).
+
+- Example: A small web application that doesn’t want to maintain complex time zone logic and prefers to make API calls for time zone conversions or current time lookups.
+
+## 4. Zero Maintenance / No Updates
+
+When to Use the API: Projects that prioritize ease of maintenance and don't want to manage or update an NPM package.
+Why: The API allows developers to simply consume the service without worrying about updating the package when new features or bug fixes are released.
+
+- Example: A project where the developer prefers that someone else maintains the service and they don’t need to worry about versioning or dependencies.
+
+## 5. Quick Prototyping or Third-Party Integrations
+
+When to Use the API: When developers are building a quick prototype or integrating a third-party tool and don't want to install additional dependencies.
+Why: The API is quick and easy to consume for rapid development without the overhead of package management.
+Example: A demo or proof-of-concept web app that needs quick timezone conversions but doesn’t want to manage NPM dependencies.
+
+## 6. Centralized Logic / Single Point of Control
+
+When to Use the API: For organizations or teams that want centralized control over timezone logic.
+Why: By using the API, an organization can ensure that all clients—mobile apps, web apps, microservices—use the same consistent logic without having to distribute the NPM package across multiple platforms.

docs/api/calculateDurationAPI.md

@@ -0,0 +1,38 @@
+# 5. Calculate Duration Between Two Dates in a Timezone
+
+Calculate the duration between two dates in a specific timezone.
+
+## Endpoint
+
+```http
+GET /calculateduration
+```
+
+## Query Parameters
+
+- startDateStr (string) – The start date in ISO format (e.g., "2024-10-15T10:00:00").
+- endDateStr (string) – The end date in ISO format (e.g., "2024-10-16T12:00:00").
+- timezone (string) – The timezone for the duration calculation (e.g., "America/New_York").
+- unit (string) – The unit for the duration (days, hours, or minutes).
+
+## Example Request
+
+```http
+GET https://world-clockify-api.onrender.com/api/v1/calculateduration?startDateStr=2024-10-15T10:00:00&endDateStr=2024-10-16T12:00:00&timezone=America/New_York&unit=hours
+```
+
+## Example Response
+
+```json
+{
+  "duration": 26
+}
+```
+
+## Error Responses
+
+```json
+{
+  "message": "Invalid unit parameters"
+}
+```

docs/api/fetchConvertedTime.md

@@ -0,0 +1,37 @@
+# 3. Convert Time Between Timezones
+
+Convert a specific date and time from one timezone to another.
+
+## Endpoint
+
+```http
+GET /converttimezone
+```
+
+## Query Parameters
+
+- date (string) – The date/time string in ISO format (e.g., "2024-10-17T10:30:00").
+- fromZone (string) – The original timezone of the date/time (e.g., "America/New_York").
+- toZone (string) – The target timezone to convert the date/time (e.g., "Europe/London").
+
+## Example Request
+
+```http
+GET https://world-clockify-api.onrender.com/api/v1/converttimezone?date=2024-10-17T10:30:00&fromZone=America/New_York&toZone=Europe/London
+```
+
+## Example Response
+
+```json
+{
+  "convertedTime": "2024-10-17T15:30:00+01:00"
+}
+```
+
+## Error Responses
+
+```json
+{
+  "message": "Invalid parameters"
+}
+```

docs/api/fetchCurrentTime.md

@@ -0,0 +1,35 @@
+# 1. Get Current Time in Timezone
+
+Retrieve the current time in a specified timezone.
+
+## Endpoint
+
+```http
+GET /currenttime
+```
+
+## Query Parameters
+
+timezone `(string)` – The timezone for which you want to fetch the current time (e.g., "America/New_York").
+
+## Example Request
+
+```http
+GET https://world-clockify-api.onrender.com/api/v1/currenttime?timezone=America/New_York
+```
+
+## Example Response
+
+```json
+{
+  "currentTime": "2024-10-17T15:30:00-04:00"
+}
+```
+
+## Error Responses
+
+```json
+{
+  "message": "Invalid timezone parameter"
+}
+```

docs/api/fetchSupportedTimezones.md

@@ -0,0 +1,23 @@
+# 2. Get List of Supported Timezones
+
+Fetch the list of all supported timezones.
+
+## Endpoint
+
+```http
+GET /supportedtimezone
+```
+
+## Example Request
+
+```http
+GET https://world-clockify-api.onrender.com/api/v1/supportedtimezone
+```
+
+## Example Response
+
+```json
+{
+  "timezones": ["Africa/Abidjan", "Africa/Cairo", "America/New_York", "Europe/London", ...]
+}
+```

docs/api/fetchTimeDifference.md

@@ -0,0 +1,36 @@
+# 4. Calculate Time Difference Between Timezones
+
+Calculate the time difference between two timezones.
+
+## Endpoint
+
+```http
+GET /timedifference
+```
+
+## Query Parameters
+
+- timezone1 (string) – The first timezone (e.g., "America/New_York").
+- timezone2 (string) – The second timezone (e.g., "Europe/London").
+
+## Example Request
+
+```http
+GET https://world-clockify-api.onrender.com/api/v1/timedifference?timezone1=America/New_York&timezone2=Europe/London
+```
+
+## Example Response
+
+```json
+{
+  "timeDifference": "5 hours"
+}
+```
+
+## Error Responses
+
+```json
+{
+  "message": "Invalid timezone parameters"
+}
+```

docs/api/formatDateInTimezoneAPI.md

@@ -0,0 +1,38 @@
+# 6. Format Date in a Specific Timezone
+
+Format a date/time string according to a specific timezone and format pattern.
+
+## Endpoint
+
+```http
+GET /formattimezone
+```
+
+## Query Parameters
+
+- date (string) – The date/time in ISO format (e.g., "2024-10-17T10:30:00").
+- fromZone (string) – The timezone of the original date/time (e.g., "America/New_York").
+- toZone (string) – The target timezone to format the date/time (e.g., "Europe/London").
+- format (string) – The date format (e.g., "yyyy-MM-dd HH:mm").
+
+## Example Request
+
+```http
+GET https://world-clockify-api.onrender.com/api/v1/formattimezone?date=2024-10-17T10:30:00&fromZone=America/New_York&toZone=Europe/London&format=yyyy-MM-dd%20HH:mm:ss
+```
+
+## Example Response
+
+```json
+{
+  "formattedTime": "2024-10-17 15:30:00"
+}
+```
+
+## Error Responses
+
+```json
+{
+  "message": "Invalid parameters"
+}
+```