# API Documentation

This document describes the API endpoints for the site monitoring application.

## Authentication

All API endpoints require authentication using Laravel Sanctum tokens. You need to be logged into the web application to generate API tokens.

### Generate an API Token

After logging into the web application, you can generate an API token by making a POST request:

```bash
POST /api/tokens
Authorization: Bearer {your-session-token}
Content-Type: application/json

{
  "token_name": "My API Token"
}
```

**Response:**
```json
{
  "token": "1|abcdef123456...",
  "type": "Bearer"
}
```

**Important:** Save this token securely. It will only be shown once.

### Using the API Token

Include the token in the `Authorization` header for all API requests:

```bash
Authorization: Bearer 1|abcdef123456...
```

### Token Management

#### List All Tokens
```bash
GET /api/tokens
Authorization: Bearer {your-token}
```

#### Revoke a Specific Token
```bash
DELETE /api/tokens/{tokenId}
Authorization: Bearer {your-token}
```

#### Revoke All Tokens
```bash
DELETE /api/tokens
Authorization: Bearer {your-token}
```

## API Endpoints

### Sites

#### List All Sites
Get all sites for the authenticated user.

```bash
GET /api/sites
Authorization: Bearer {your-token}
```

**Response:**
```json
{
  "data": [
    {
      "id": 1,
      "user_id": 1,
      "url": "https://example.com",
      "name": "My Website",
      "monitoring_enabled": true,
      "uptime_checks_count": 150,
      "ssl_certificates_count": 5,
      "broken_links_count": 3,
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-15T12:00:00.000000Z"
    }
  ]
}
```

#### Get a Specific Site
```bash
GET /api/sites/{site}
Authorization: Bearer {your-token}
```

**Response:**
```json
{
  "data": {
    "id": 1,
    "user_id": 1,
    "url": "https://example.com",
    "name": "My Website",
    "monitoring_enabled": true,
    "uptime_checks_count": 150,
    "ssl_certificates_count": 5,
    "broken_links_count": 3,
    "created_at": "2024-01-01T00:00:00.000000Z",
    "updated_at": "2024-01-15T12:00:00.000000Z"
  }
}
```

### Uptime Monitoring

#### Get Uptime History
Get paginated uptime check history for a site.

```bash
GET /api/sites/{site}/uptime?per_page=50
Authorization: Bearer {your-token}
```

**Query Parameters:**
- `per_page` (optional): Number of results per page (1-100, default: 50)

**Response:**
```json
{
  "current_page": 1,
  "data": [
    {
      "id": 1,
      "site_id": 1,
      "status_code": 200,
      "response_time_ms": 245,
      "checked_at": "2024-01-15T12:00:00.000000Z",
      "created_at": "2024-01-15T12:00:00.000000Z"
    }
  ],
  "first_page_url": "http://localhost/api/sites/1/uptime?page=1",
  "from": 1,
  "last_page": 3,
  "last_page_url": "http://localhost/api/sites/1/uptime?page=3",
  "links": [...],
  "next_page_url": "http://localhost/api/sites/1/uptime?page=2",
  "path": "http://localhost/api/sites/1/uptime",
  "per_page": 50,
  "prev_page_url": null,
  "to": 50,
  "total": 150
}
```

#### Get Uptime Statistics
Get uptime statistics for a site.

```bash
GET /api/sites/{site}/uptime/stats
Authorization: Bearer {your-token}
```

**Response:**
```json
{
  "data": {
    "total_checks": 150,
    "successful_checks": 147,
    "uptime_percentage": 98.0,
    "average_response_time_ms": 234.56,
    "latest_check": {
      "id": 150,
      "site_id": 1,
      "status_code": 200,
      "response_time_ms": 245,
      "checked_at": "2024-01-15T12:00:00.000000Z",
      "created_at": "2024-01-15T12:00:00.000000Z"
    }
  }
}
```

### SSL Certificate Monitoring

#### Get SSL Certificate Data
Get the latest SSL certificate information for a site.

```bash
GET /api/sites/{site}/ssl
Authorization: Bearer {your-token}
```

**Response:**
```json
{
  "data": {
    "issuer": "Let's Encrypt Authority X3",
    "expires_at": "2024-04-15T00:00:00.000000Z",
    "checked_at": "2024-01-15T12:00:00.000000Z",
    "days_until_expiry": 90,
    "is_expiring_soon": false,
    "is_expired": false
  }
}
```

#### Get SSL Certificate History
Get paginated SSL certificate check history.

```bash
GET /api/sites/{site}/ssl/history?per_page=20
Authorization: Bearer {your-token}
```

**Query Parameters:**
- `per_page` (optional): Number of results per page (1-100, default: 20)

**Response:**
```json
{
  "current_page": 1,
  "data": [
    {
      "id": 5,
      "site_id": 1,
      "issuer": "Let's Encrypt Authority X3",
      "expires_at": "2024-04-15T00:00:00.000000Z",
      "checked_at": "2024-01-15T12:00:00.000000Z",
      "created_at": "2024-01-15T12:00:00.000000Z"
    }
  ],
  "first_page_url": "...",
  "last_page": 1,
  "per_page": 20,
  "total": 5
}
```

### Broken Links

#### Get Broken Links List
Get paginated list of broken links for a site.

```bash
GET /api/sites/{site}/links?per_page=50
Authorization: Bearer {your-token}
```

**Query Parameters:**
- `per_page` (optional): Number of results per page (1-100, default: 50)

**Response:**
```json
{
  "current_page": 1,
  "data": [
    {
      "id": 1,
      "site_id": 1,
      "url": "https://example.com/broken-page",
      "status_code": 404,
      "last_checked_at": "2024-01-15T12:00:00.000000Z",
      "created_at": "2024-01-15T12:00:00.000000Z"
    }
  ],
  "first_page_url": "...",
  "last_page": 1,
  "per_page": 50,
  "total": 3
}
```

#### Get Broken Links Statistics
Get statistics about broken links for a site.

```bash
GET /api/sites/{site}/links/stats
Authorization: Bearer {your-token}
```

**Response:**
```json
{
  "data": {
    "total_broken_links": 3,
    "status_code_breakdown": [
      {
        "status_code": 404,
        "count": 2
      },
      {
        "status_code": 500,
        "count": 1
      }
    ]
  }
}
```

## Error Responses

### Unauthorized (401)
```json
{
  "message": "Unauthenticated."
}
```

### Forbidden (403)
```json
{
  "message": "Unauthorized"
}
```

### Not Found (404)
```json
{
  "message": "No SSL certificate data found"
}
```

### Validation Error (422)
```json
{
  "message": "The per_page field must be an integer.",
  "errors": {
    "per_page": [
      "The per_page field must be an integer."
    ]
  }
}
```

## Example Usage

### Using cURL

```bash
# List all sites
curl -X GET http://localhost/api/sites \
  -H "Authorization: Bearer 1|abcdef123456..." \
  -H "Accept: application/json"

# Get uptime history
curl -X GET "http://localhost/api/sites/1/uptime?per_page=25" \
  -H "Authorization: Bearer 1|abcdef123456..." \
  -H "Accept: application/json"

# Get SSL certificate data
curl -X GET http://localhost/api/sites/1/ssl \
  -H "Authorization: Bearer 1|abcdef123456..." \
  -H "Accept: application/json"
```

### Using JavaScript (Fetch API)

```javascript
const apiToken = '1|abcdef123456...';
const baseUrl = 'http://localhost/api';

// List all sites
const response = await fetch(`${baseUrl}/sites`, {
  headers: {
    'Authorization': `Bearer ${apiToken}`,
    'Accept': 'application/json'
  }
});

const data = await response.json();
console.log(data);
```

### Using Python (requests)

```python
import requests

api_token = '1|abcdef123456...'
base_url = 'http://localhost/api'

headers = {
    'Authorization': f'Bearer {api_token}',
    'Accept': 'application/json'
}

# List all sites
response = requests.get(f'{base_url}/sites', headers=headers)
data = response.json()
print(data)
```

## Rate Limiting

API requests are subject to Laravel's default rate limiting (60 requests per minute for authenticated users). If you exceed the rate limit, you'll receive a `429 Too Many Requests` response.

## Security Best Practices

1. **Never share your API tokens** - Keep them secure and treat them like passwords
2. **Use HTTPS in production** - Always use encrypted connections when making API requests
3. **Rotate tokens regularly** - Periodically revoke and recreate your API tokens
4. **Use separate tokens for different applications** - Create named tokens for each integration
5. **Revoke unused tokens** - Remove tokens that are no longer needed