some progress
This commit is contained in:
Doar Mihai
@@ -0,0 +1,406 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user