landing_page/API_INTERFACE.md

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)

{
  "data": <Payload Object | Array>
}

Error Response (4xx / 5xx)

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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"
            }
          ]
        }
      ]
    }
  ]
}