# AI Agent Networking Lab (ANL) — REST API Interface Specification

This document defines the RESTful API endpoints, request parameters, response schemas, and data structures provided by the ANL Go/Gin backend server.

---

## 1. General API Conventions

### 1.1 Base URL
- **Local Development**: `http://localhost:8080/api/v1`
- **Protocol**: HTTP/1.1 (JSON Content-Type: `application/json; charset=utf-8`)

### 1.2 Standard Response Envelope

All API endpoints strictly follow the uniform JSON response envelope structure.

#### Success Response (`200 OK`)
```json
{
  "data": <Payload Object | Array>
}
```

#### Error Response (`4xx / 5xx`)
```json
{
  "error": {
    "message": "Human-readable error description"
  }
}
```

### 1.3 HTTP Status Codes
| Status Code | Description |
|---|---|
| `200 OK` | The request succeeded and returned the requested data. |
| `400 Bad Request` | Invalid query parameter (e.g., unsupported publication category). |
| `404 Not Found` | The requested resource was not found. |
| `500 Internal Server Error` | Unexpected server-side failure during database query or processing. |

---

## 2. API Endpoints Specification

### 2.1 System & Health

#### `GET /api/v1/health`
Checks backend API service health and database availability.

- **Response Payload**:
```json
{
  "data": {
    "service": "anl-backend-api",
    "status": "ok"
  }
}
```

---

## 2.2 Home & Overview

#### `GET /api/v1/research-projects`
Retrieves the list of all active research projects.

- **Response Payload**:
```json
{
  "data": [
    {
      "id": 1,
      "slug": "iot-standards",
      "title": "AIoT & AI-RAN",
      "abstract": "AIoT & AI-RAN investigates agent-based IoT architectures in which autonomous AI agents are distributed across sensor, edge, and radio access layers. The project studies agent-to-agent coordination over high-performance transport (gRPC/QUIC) bridged with constrained edge protocols (MQTT/CoAP), targeting AI-RAN designs for distributed autonomous control.",
      "keywords": [
        "AIoT",
        "agent-based IoT",
        "AI-RAN",
        "constrained edge protocols",
        "distributed autonomous control"
      ],
      "organization": "National Research Foundation of Korea (NRF)",
      "standards_org": "NRF",
      "period": "2026 ~ Present",
      "funder": null,
      "created_at": "2026-08-24T16:47:14Z",
      "updated_at": "2026-08-24T16:47:14Z"
    }
  ]
}
```

#### `GET /api/v1/research-areas`
Retrieves the list of 14 core research areas ordered by `display_order`.

- **Response Payload**:
```json
{
  "data": [
    {
      "id": 1,
      "name_en": "Quick UDP Internet Connection (QUIC)",
      "name_kr": null,
      "display_order": 1
    },
    {
      "id": 2,
      "name_en": "QUIC-based Mobility and Multi-Streaming Support",
      "name_kr": null,
      "display_order": 2
    }
  ]
}
```

#### `GET /api/v1/stats/summary`
Retrieves aggregated top-level metrics for the homepage hero section.

- **Response Payload**:
```json
{
  "data": {
    "intl_publications": 68,
    "standardization_docs": 44,
    "patents": 75
  }
}
```

---

## 2.3 Members & Alumni

#### `GET /api/v1/members`
Retrieves all 16 active members (including the professor and graduate researchers) ordered by `display_order`.

- **Response Payload**:
```json
{
  "data": [
    {
      "id": 1,
      "name_ko": "고석주",
      "name_en": "Seok-Joo Koh",
      "degree": "Professor",
      "affiliation": "School of Computer Science and Engineering",
      "email": "sjkoh@knu.ac.kr",
      "is_advisor": true,
      "display_order": 1,
      "created_at": "2026-08-24T16:47:14Z"
    },
    {
      "id": 2,
      "name_ko": "김경호",
      "name_en": "Kyeong-Ho Kim",
      "degree": "PhDStudent",
      "affiliation": null,
      "email": null,
      "is_advisor": false,
      "display_order": 2,
      "created_at": "2026-08-24T16:47:14Z"
    }
  ]
}
```

#### `GET /api/v1/alumni`
Retrieves all 60 alumni sorted chronologically by `graduated_at DESC`.

- **Response Payload**:
```json
{
  "data": [
    {
      "id": 1,
      "name_ko": "도경진",
      "name_en": "Gyeong-Jin Do",
      "degree": "MS",
      "graduated_at": "2024-02",
      "major": "School of Electronic and Electrical Engineering",
      "current_position": "LIG Nex1, Senior Researcher",
      "created_at": "2026-08-24T16:47:14Z"
    }
  ]
}
```

---

## 2.4 Publications & Intellectual Property

#### `GET /api/v1/publications`
Retrieves list of academic publications. Supports filtering by publication category.

- **Query Parameters**:
  - `category` (optional, string): Filter by category. Allowed values: `intl-journal-conf`, `domestic-journal-conf`.
- **Response Payload**:
```json
{
  "data": [
    {
      "id": 1,
      "category": "intl-journal-conf",
      "title": "Globally Integrated Trust Authority (GITA) for Resource-Constrained Edge Devices in IoT and 6G",
      "authors": "Seok-Joo Koh, ...",
      "venue": "IEEE Transactions on Network and Service Management",
      "volume": "Vol. 23, pp. 4490~4505, April 2026",
      "published_at": "2026-04",
      "kci": false,
      "doi": "10.1109/TNSM.2026.10908861",
      "is_highlight": true,
      "created_at": "2026-08-24T16:47:14Z"
    }
  ]
}
```

#### `GET /api/v1/publications/highlights`
Retrieves the **5 designated top representative publications** (`WHERE is_highlight = 1`).

- **Response Payload**:
```json
{
  "data": [
    {
      "id": 1,
      "category": "intl-journal-conf",
      "title": "Globally Integrated Trust Authority (GITA) for Resource-Constrained Edge Devices in IoT and 6G",
      "authors": "Seok-Joo Koh, ...",
      "venue": "IEEE Transactions on Network and Service Management",
      "volume": "Vol. 23, pp. 4490~4505, April 2026",
      "published_at": "2026-04",
      "kci": false,
      "doi": "10.1109/TNSM.2026.10908861",
      "is_highlight": true,
      "created_at": "2026-08-24T16:47:14Z"
    },
    {
      "id": 2,
      "category": "intl-journal-conf",
      "title": "Application Level Trust Authority (APPLETA) for Resource-Constrained Edge Devices in IoT and 6G",
      "authors": "Seok-Joo Koh, ...",
      "venue": "IEEE Transactions on Consumer Electronics",
      "volume": "Vol. 71, pp. 1120~1135, Jan. 2026",
      "published_at": "2026-01",
      "kci": false,
      "doi": "10.1109/TCE.2025.3524673",
      "is_highlight": true,
      "created_at": "2026-08-24T16:47:14Z"
    }
  ]
}
```

#### `GET /api/v1/patents`
Retrieves all 75 registered and pending patents sorted by `published_at DESC`.

- **Response Payload**:
```json
{
  "data": [
    {
      "id": 1,
      "title": "다중 인터페이스 기반 QUIC 핸드오버 지원 장치 및 방법",
      "inventors": "고석주, 김경호",
      "application_no": "10-2024-0012345",
      "application_at": "2024-01-15",
      "registration_no": "10-2567890",
      "registration_at": "2025-05-20",
      "country": "KR",
      "published_at": "2025-05-20",
      "created_at": "2026-08-24T16:47:14Z"
    }
  ]
}
```

---

## 2.5 Lectures & Curriculum

#### `GET /api/v1/semesters`
Retrieves all 45 academic semesters with nested course lists, ordered by `year DESC` and `term` (Fall before Spring).

- **Response Payload**:
```json
{
  "data": [
    {
      "id": 1,
      "year": 2026,
      "term": "Spring",
      "courses": [
        {
          "id": 1,
          "semester_id": 1,
          "code": "COMP0411",
          "name_en": "Computer Networks",
          "name_kr": null,
          "note": "Undergraduate Core",
          "display_order": 1
        }
      ]
    },
    {
      "id": 2,
      "year": 2025,
      "term": "Fall",
      "courses": [
        {
          "id": 2,
          "semester_id": 2,
          "code": "COMP0754",
          "name_en": "Advanced Internet Protocol",
          "name_kr": null,
          "note": "Graduate Course",
          "display_order": 1
        }
      ]
    }
  ]
}
```

---

## 2.6 Standardization

#### `GET /api/v1/standards-bodies`
Retrieves all 6 standardization bodies with 3-tier hierarchy (`Body → Project (WG) → Documents[]`).

- **Response Payload**:
```json
{
  "data": [
    {
      "id": 1,
      "org": "IEC TC100",
      "full_name": "International Electrotechnical Commission: Technical Committee 100",
      "scope": "international",
      "period": "2018 ~ Present",
      "role": "Project Editor / Active Contributor",
      "display_order": 1,
      "projects": [
        {
          "wg": "WG 12",
          "name": "MCM: Multilateral and Collaborative Metaverse",
          "documents": [
            {
              "id": 1,
              "body_id": 1,
              "wg": "WG 12",
              "project_name": "MCM: Multilateral and Collaborative Metaverse",
              "title": "Conceptual model for multilateral and collaborative metaverse systems",
              "doc_ref": "IEC 63430 ED1",
              "status": "IS",
              "published_at": "2026-03"
            }
          ]
        }
      ]
    }
  ]
}
```
