# Open5G2GO: API Reference

# API Reference

Open5G2GO provides a REST API for programmatic access to subscriber management and system monitoring.

## Overview

| Property | Value |
|----------|-------|
| Base URL | `http://YOUR_HOST:8080/api/v1` |
| Content-Type | `application/json` |
| Authentication | None (MVP) |

### Interactive Documentation

The API provides interactive documentation at runtime:

* **Swagger UI**: `http://YOUR_HOST:8080/api/v1/docs`
* **ReDoc**: `http://YOUR_HOST:8080/api/v1/redoc`
* **OpenAPI Schema**: `http://YOUR_HOST:8080/api/v1/openapi.json`


---

## Health & System Endpoints

### Health Check

```
GET /api/v1/health
```

**Response:**

```json
{
  "status": "healthy",
  "version": "0.1.0",
  "service": "Open5G2GO Web API"
}
```

### System Status

```
GET /api/v1/status
```

Returns overall system health including subscriber counts, eNodeB status, and operational state.

### Service Status

```
GET /api/v1/services
```

Returns status of all Open5GS core services (MME, HSS, SGW, etc.).


---

## Subscriber Management

### List All Subscribers

```
GET /api/v1/subscribers
```

**Response:**

```json
{
  "timestamp": "2024-01-15 10:30:00 UTC",
  "total": 10,
  "subscribers": [
    {
      "imsi": "315010000000001",
      "name": "CAM-01",
      "apn": "internet",
      "ip": "10.48.99.2"
    }
  ]
}
```

### Get Subscriber Details

```
GET /api/v1/subscribers/{imsi}
```

| Parameter | Type | Description |
|-----------|------|-------------|
| `imsi`    | string | 15-digit IMSI |

### Add Subscriber

```
POST /api/v1/subscribers
```

**Request Body:**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `imsi` | string | Yes      | Full 15-digit IMSI from SIM card |
| `name` | string | No       | Friendly device name (max 50 chars) |
| `apn` | string | No       | Access Point Name (default: "internet") |
| `ip`  | string | No       | Static IP address (auto-assigned if omitted) |

**Example:**

```json
{
  "imsi": "315010000000001",
  "name": "Camera-01"
}
```

**Response (201 Created):**

```json
{
  "success": true,
  "subscriber": {
    "imsi": "315010000000001",
    "name": "Camera-01",
    "ip": "10.48.99.2",
    "apn": "internet"
  }
}
```

### Update Subscriber

```
PUT /api/v1/subscribers/{imsi}
```

**Request Body:**

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | New device name |
| `apn` | string | New Access Point Name |
| `ip`  | string | New static IP address |

At least one field must be provided.

### Delete Subscriber

```
DELETE /api/v1/subscribers/{imsi}
```

> **Warning:** Deleting a subscriber immediately disconnects the device from the network.


---

## Network Configuration

### Get Network Configuration

```
GET /api/v1/config
```

Returns network identity (PLMN), eNodeB config, APNs, and IP pool settings.


---

## eNodeB Management

### Get eNodeB Status

```
GET /api/v1/enodeb/status
```

Returns connected eNodeBs via S1AP and SNMP monitoring data.

### Refresh eNodeB Status

```
POST /api/v1/enodeb/refresh
```

Force refresh of eNodeB status data.


---

## Active Connections

### Get Active Connections

```
GET /api/v1/connections
```

Returns currently connected devices with their status.


---

## Error Handling

All endpoints return consistent error responses:

```json
{
  "error": "Error message",
  "details": "Additional context"
}
```

**HTTP Status Codes:**

| Code | Description |
|------|-------------|
| 200  | Success     |
| 201  | Created (new subscriber) |
| 400  | Bad Request (validation error) |
| 404  | Not Found   |
| 500  | Internal Server Error |


---

## Code Examples

### cURL

```bash
# Health check
curl http://localhost:8080/api/v1/health

# List subscribers
curl http://localhost:8080/api/v1/subscribers

# Add subscriber
curl -X POST http://localhost:8080/api/v1/subscribers \
  -H "Content-Type: application/json" \
  -d '{"imsi": "315010000000001", "name": "Camera-01"}'

# Delete subscriber
curl -X DELETE http://localhost:8080/api/v1/subscribers/315010000000001
```

### Python

```python
import requests

BASE_URL = "http://localhost:8080/api/v1"

# List subscribers
response = requests.get(f"{BASE_URL}/subscribers")
subscribers = response.json()

# Add subscriber
new_device = {"imsi": "315010000000001", "name": "Camera-01"}
response = requests.post(f"{BASE_URL}/subscribers", json=new_device)
```


---

## Notes

* **Authentication**: The MVP does not implement authentication. All endpoints are publicly accessible.
* **Rate Limiting**: Not implemented in MVP. Use a reverse proxy for production.
* **Interactive Docs**: Use Swagger UI at `/api/v1/docs` for testing endpoints directly.