# NHN Cloud API 명세서

## 기본 정보

- **Base URL**: `http://{server}:8900/api/nhn`
- **Swagger UI**: `http://{server}:8900/swagger/`
- **Content-Type**: `application/json`

---

## 인증 방식

모든 API 호출 시 아래 헤더를 포함해야 합니다:

| 헤더 | 필수 | 설명 |
|------|------|------|
| `X-NHN-Region` | O | NHN Cloud 리전 (`kr1`: 판교, `kr2`: 평촌) |
| `X-NHN-Token` | O | NHN Cloud API 토큰 |
| `X-NHN-Tenant-ID` | △ | 테넌트 ID (Compute API에서 필수) |
| `X-NHN-Storage-Account` | △ | 스토리지 계정 (Storage API에서 필수) |

---

## 1. Token API

### 1.1 토큰 생성

NHN Cloud API 인증 토큰을 발급받습니다.

```
POST /api/nhn/token/
```

**Request Body**
```json
{
  "tenant_id": "04a2c5b7de7e4d66b970ad950081a7c3",
  "username": "user@example.com",
  "password": "your-api-password"
}
```

**Response (200 OK)**
```json
{
  "token": "gAAAAABm...",
  "tenant_id": "04a2c5b7de7e4d66b970ad950081a7c3",
  "expires_at": "2024-01-15T12:00:00Z"
}
```

**Error Response (401)**
```json
{
  "error": "인증 실패 메시지",
  "code": 401
}
```

---

## 2. Compute API

### 2.1 Flavor 목록 조회

```
GET /api/nhn/compute/flavors/
```

**Headers**
```
X-NHN-Region: kr2
X-NHN-Token: {token}
X-NHN-Tenant-ID: {tenant_id}
```

**Response (200 OK)**
```json
{
  "flavors": [
    {
      "id": "flavor-id-123",
      "name": "m2.c2m4",
      "vcpus": 2,
      "ram": 4096,
      "disk": 0
    }
  ]
}
```

---

### 2.2 Keypair 목록 조회

```
GET /api/nhn/compute/keypairs/
```

**Response (200 OK)**
```json
{
  "keypairs": [
    {
      "keypair": {
        "name": "my-keypair",
        "public_key": "ssh-rsa AAAA...",
        "fingerprint": "xx:xx:xx..."
      }
    }
  ]
}
```

---

### 2.3 이미지 목록 조회

```
GET /api/nhn/compute/images/
```

**Response (200 OK)**
```json
{
  "images": [
    {
      "id": "image-id-123",
      "name": "Ubuntu 20.04",
      "status": "active",
      "created_at": "2024-01-01T00:00:00Z"
    }
  ]
}
```

---

### 2.4 인스턴스 목록 조회

```
GET /api/nhn/compute/instances/
```

**Response (200 OK)**
```json
{
  "servers": [
    {
      "id": "server-id-123",
      "name": "my-instance",
      "status": "ACTIVE",
      "addresses": {
        "Default Network": [
          {"addr": "192.168.0.10", "version": 4}
        ]
      },
      "created": "2024-01-01T00:00:00Z"
    }
  ]
}
```

---

### 2.5 인스턴스 상세 조회

```
GET /api/nhn/compute/instances/{server_id}/
```

**Response (200 OK)**
```json
{
  "server": {
    "id": "server-id-123",
    "name": "my-instance",
    "status": "ACTIVE",
    "flavor": {"id": "flavor-id"},
    "image": {"id": "image-id"},
    "addresses": {...},
    "created": "2024-01-01T00:00:00Z"
  }
}
```

---

### 2.6 인스턴스 생성

```
POST /api/nhn/compute/instances/create/
```

**Request Body**
```json
{
  "name": "my-new-instance",
  "image_id": "image-id-123",
  "flavor_id": "flavor-id-123",
  "subnet_id": "subnet-id-123",
  "keypair_name": "my-keypair",
  "volume_size": 50,
  "security_groups": ["default"],
  "availability_zone": "kr-pub-a"
}
```

| 필드 | 타입 | 필수 | 설명 |
|------|------|------|------|
| name | string | O | 인스턴스 이름 |
| image_id | string | O | 이미지 ID |
| flavor_id | string | O | Flavor ID |
| subnet_id | string | O | 서브넷 ID |
| keypair_name | string | O | Keypair 이름 |
| volume_size | integer | X | 볼륨 크기 (GB, 기본 50) |
| security_groups | array | X | 보안 그룹 (기본 ["default"]) |
| availability_zone | string | X | 가용 영역 |

**Response (201 Created)**
```json
{
  "server": {
    "id": "new-server-id",
    "name": "my-new-instance",
    ...
  }
}
```

---

### 2.7 인스턴스 삭제

```
DELETE /api/nhn/compute/instances/{server_id}/
```

**Response (204 No Content)**

---

### 2.8 인스턴스 액션 (시작/정지/재부팅)

```
POST /api/nhn/compute/instances/{server_id}/action/
```

**Request Body**
```json
{
  "action": "start"  // "start" | "stop" | "reboot"
}
```

**Response (200 OK)**
```json
{
  "status": "success",
  "action": "start"
}
```

---

## 3. VPC API

### 3.1 VPC 목록 조회

```
GET /api/nhn/vpc/
```

**Headers**
```
X-NHN-Region: kr2
X-NHN-Token: {token}
```

**Response (200 OK)**
```json
{
  "vpcs": [
    {
      "id": "vpc-id-123",
      "name": "my-vpc",
      "cidrv4": "10.0.0.0/16",
      "state": "available"
    }
  ]
}
```

---

### 3.2 VPC 생성

```
POST /api/nhn/vpc/create/
```

**Request Body**
```json
{
  "name": "my-new-vpc",
  "cidr": "10.0.0.0/16"
}
```

**Response (201 Created)**
```json
{
  "vpc": {
    "id": "new-vpc-id",
    "name": "my-new-vpc",
    "cidrv4": "10.0.0.0/16"
  }
}
```

---

### 3.3 VPC 상세 조회

```
GET /api/nhn/vpc/{vpc_id}/
```

---

### 3.4 VPC 삭제

```
DELETE /api/nhn/vpc/{vpc_id}/
```

**Response (204 No Content)**

---

### 3.5 서브넷 목록 조회

```
GET /api/nhn/subnet/
```

**Response (200 OK)**
```json
{
  "vpcsubnets": [
    {
      "id": "subnet-id-123",
      "name": "my-subnet",
      "vpc_id": "vpc-id-123",
      "cidr": "10.0.1.0/24",
      "gateway": "10.0.1.1"
    }
  ]
}
```

---

### 3.6 서브넷 생성

```
POST /api/nhn/subnet/create/
```

**Request Body**
```json
{
  "vpc_id": "vpc-id-123",
  "name": "my-new-subnet",
  "cidr": "10.0.1.0/24"
}
```

---

### 3.7 서브넷 상세 조회 / 삭제

```
GET /api/nhn/subnet/{subnet_id}/
DELETE /api/nhn/subnet/{subnet_id}/
```

---

### 3.8 Floating IP 목록 조회

```
GET /api/nhn/floatingip/
```

**Response (200 OK)**
```json
{
  "floatingips": [
    {
      "id": "fip-id-123",
      "floating_ip_address": "133.186.xxx.xxx",
      "status": "ACTIVE",
      "port_id": "port-id-123"
    }
  ]
}
```

---

## 4. NKS (Kubernetes) API

### 4.1 지원 버전 조회

```
GET /api/nhn/nks/supports/
```

**Headers**
```
X-NHN-Region: kr2
X-NHN-Token: {token}
```

**Response (200 OK)**
```json
{
  "supported_k8s": {
    "v1.33.4": "True",
    "v1.32.4": "True",
    "v1.31.4": "True",
    "v1.30.4": "False"
  },
  "supported_event_type": {...}
}
```

---

### 4.2 클러스터 목록 조회

```
GET /api/nhn/nks/clusters/
```

**Headers**
```
X-NHN-Region: kr2
X-NHN-Token: {token}
```

**Response (200 OK)**
```json
{
  "clusters": [
    {
      "uuid": "cluster-uuid-123",
      "name": "my-cluster",
      "status": "CREATE_COMPLETE",
      "node_count": 3
    }
  ]
}
```

---

### 4.3 클러스터 상세 조회

```
GET /api/nhn/nks/clusters/{cluster_name}/
```

---

### 4.4 클러스터 kubeconfig 조회

```
GET /api/nhn/nks/clusters/{cluster_name}/config/
```

**Response (200 OK)**
```json
{
  "config": "apiVersion: v1\nclusters:\n- cluster:..."
}
```

---

### 4.5 클러스터 생성

```
POST /api/nhn/nks/clusters/create/
```

**Request Body**
```json
{
  "cluster_name": "my-k8s-cluster",
  "vpc_id": "vpc-id-123",
  "subnet_id": "subnet-id-123",
  "instance_type": "m2.c4m8",
  "keypair_name": "my-keypair",
  "kubernetes_version": "v1.28.3",
  "availability_zone": "kr-pub-a",
  "is_public": true,
  "external_network_id": "ext-net-id",
  "external_subnet_id": "ext-subnet-id",
  "node_count": 3,
  "boot_volume_size": 50,
  "boot_volume_type": "General SSD"
}
```

| 필드 | 타입 | 필수 | 설명 |
|------|------|------|------|
| cluster_name | string | O | 클러스터 이름 |
| vpc_id | string | O | VPC ID |
| subnet_id | string | O | 서브넷 ID |
| instance_type | string | O | 인스턴스 타입 (Flavor ID) |
| keypair_name | string | O | Keypair 이름 |
| kubernetes_version | string | O | K8s 버전 (예: v1.28.3) |
| availability_zone | string | O | 가용 영역 |
| is_public | boolean | X | Public 클러스터 여부 (기본 true) |
| external_network_id | string | △ | 외부 네트워크 ID (Public 필수) |
| external_subnet_id | string | △ | 외부 서브넷 ID (Public 필수) |
| node_count | integer | X | 노드 수 (기본 1) |
| boot_volume_size | integer | X | 부팅 볼륨 크기 (기본 50GB) |
| boot_volume_type | string | X | 볼륨 타입 (기본 General SSD) |

---

### 4.6 클러스터 삭제

```
DELETE /api/nhn/nks/clusters/{cluster_name}/
```

**Response (204 No Content)**

---

## 5. Object Storage API

### 5.1 컨테이너 목록 조회

```
GET /api/nhn/storage/containers/
```

**Headers**
```
X-NHN-Region: kr2
X-NHN-Token: {token}
X-NHN-Storage-Account: AUTH_xxxxxxxx
```

**Response (200 OK)**
```json
{
  "containers": ["container1", "container2", "container3"]
}
```

---

### 5.2 컨테이너 생성

```
POST /api/nhn/storage/containers/create/
```

**Request Body**
```json
{
  "name": "my-new-container"
}
```

**Response (201 Created)**
```json
{
  "status": 201,
  "container": "my-new-container"
}
```

---

### 5.3 컨테이너 오브젝트 목록 조회

```
GET /api/nhn/storage/containers/{container_name}/
```

**Response (200 OK)**
```json
{
  "objects": ["file1.txt", "file2.png", "folder/file3.json"]
}
```

---

### 5.4 컨테이너 삭제

```
DELETE /api/nhn/storage/containers/{container_name}/
```

**Response (204 No Content)**

---

## 에러 응답

모든 API는 실패 시 아래 형식으로 에러를 반환합니다:

```json
{
  "error": "에러 메시지",
  "code": 400
}
```

| HTTP Status | 설명 |
|-------------|------|
| 400 | 잘못된 요청 (파라미터 오류) |
| 401 | 인증 실패 (토큰 없음/만료) |
| 403 | 권한 없음 |
| 404 | 리소스 없음 |
| 500 | 서버 내부 오류 |

---

## 프론트엔드 사용 예시 (JavaScript)

```javascript
// 1. 토큰 발급
const tokenResponse = await fetch('/api/nhn/token/', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    tenant_id: 'your-tenant-id',
    username: 'user@example.com',
    password: 'your-password'
  })
});
const { token, tenant_id } = await tokenResponse.json();

// 2. API 호출 (인스턴스 목록)
const instancesResponse = await fetch('/api/nhn/compute/instances/', {
  headers: {
    'X-NHN-Region': 'kr2',
    'X-NHN-Token': token,
    'X-NHN-Tenant-ID': tenant_id
  }
});
const instances = await instancesResponse.json();
```

---

## 리전 정보

| 리전 코드 | 위치 |
|-----------|------|
| kr1 | 판교 |
| kr2 | 평촌 |