Volume 11 · API Reference
เล่มนี้รวบรวม API surface ของระบบ VTRC ทั้งหมด — ทุก endpoint, ทุก GraphQL operation, header, error code, และ pattern การเรียก — เพื่อให้สามารถค้นหา signature และพฤติกรรมของ API ได้โดยไม่ต้องเปิด codebase
เล่มนี้คืออะไร
Volume 11 เป็น API reference ครอบคลุม 3 backend services ของระบบ VTRC:
- vtrc-api — service หลักที่ frontend ทั้งคู่ยิงเข้ามา (GraphQL + REST)
- cu-central-api — service ที่ vtrc-api forward ไป (GraphQL + REST auth)
- centralize-api — NestJS facade สำหรับ HRMI MSSQL (REST + Swagger)
เล่มนี้เน้น what (มี endpoint อะไร, signature อย่างไร, return อะไร) มากกว่า how (business logic ทำงานอย่างไร — อยู่ใน Volume 12)
ตัวเลขที่ควรจำ
| ตัวเลข | ค่า | ที่มา |
|---|---|---|
| Backend services | 3 | vtrc-api, cu-central-api, centralize-api |
| รวม GraphQL operations | ~348 | 265 (vtrc-api) + 83 (cu-central-api) |
| รวม REST endpoints | 52 | 30 (vtrc-api) + 5 (cu-central-api) + 17 (centralize-api) |
| GraphQL subscriptions | 0 | ทุก service เป็น Query/Mutation เท่านั้น |
| vtrc-api typeDefs files | 44 | vtrc-api/api/src/typeDefs/ |
| vtrc-api resolver files | 42 | vtrc-api/api/src/resolvers/ |
| cu-central-api typeDefs files | 32 | cu-central-api/main-api/src/typeDefs/ |
| cu-central-api resolver files | 27 | cu-central-api/main-api/src/resolvers/ |
| centralize-api controllers | 4 | centralize-api/src/*.controller.ts |
| centralize-api DTOs | 19 | centralize-api/src/dto/ |
| ภาษาที่ใช้ | JavaScript (vtrc-api + cu-central-api) + TypeScript (centralize-api) | — |
| Framework | Apollo Server 2 + Express (vtrc-api + cu-central-api) + NestJS 9 (centralize-api) | — |
| API docs | Swagger/OpenAPI เฉพาะ centralize-api (/docs) | — |
ภาพรวม 3 services ใน 1 ตาราง
| ด้าน | vtrc-api | cu-central-api | centralize-api |
|---|---|---|---|
| ภาษา | JS (ESM) | JS (ESM) | TypeScript |
| Framework | Apollo 2 + Express | Apollo 2 + Express | NestJS 9 |
| ประเภท API | GraphQL + REST | GraphQL + REST | REST เท่านั้น |
| Port | 8081 | CODE_DEFAULT 8080 (CLIENT_TARGET ตัวอย่าง 8082) | 3000 |
| Path หลัก | /api/graphql (prod) /api-uat/graphql (UAT) | /api/graphql | /api/* (global prefix) |
| DB | MariaDB (vtrc + vtrc-centralize) | MSSQL (5 connections) | MSSQL (2 connections) |
| Auth | JWT + apiKey (6 APP_TYPE) | JWT + apiKey (2 levels) + LDAP | JWT guard (bypassed) |
| SourceDB sharding | ไม่มี | มี (per-row column) | มี (per-DB union) |
| Docs | ไม่มี | ไม่มี | Swagger /docs |
| Caller | frontend ทั้งคู่ | vtrc-api (ผ่าน END_POINT_CENTRALIZE) | ไม่ยืนยันใน workspace นี้ |
สไตล์การอ่านเล่มนี้
- ถ้าสนใจ endpoint เฉพาะ → ไป บท 10.3 (vtrc-api GraphQL) หรือ บท 10.5 (cu-central-api)
- ถ้าสนใจ auth/headers → ไป บท 10.2
- ถ้าสนใจ error code → ไป บท 10.7
- ถ้าสนใจ file upload/download → ไป บท 10.8
- ถ้าสนใจ forward pattern → ไป บท 10.9
สิ่งที่ Volume นี้ไม่ cover
- Business logic ของ resolver/service — cover ใน Volume 12
- DB schema และ model — cover ใน Volume 9
- Deployment topology — cover ใน Volume 2 และ Volume 13
- Security vulnerability analysis — cover ใน Volume 10
โครงสร้างบท
| บท | ชื่อ | คำถามที่ตอบ |
|---|---|---|
| 10.1 | API topology | มีกี่ service, transport อะไร, เลือกใช้ตัวไหน |
| 10.2 | Auth & headers reference | ส่ง header อะไร, apiKey ทำงานอย่างไร, JWT อย่างไร |
| 10.3 | vtrc-api GraphQL catalog | 265 operations จัดกลุ่ม + signature ตัวอย่าง |
| 10.4 | vtrc-api REST surface | 30 endpoints ใน routes.js |
| 10.5 | cu-central-api GraphQL + REST | 83 ops + 5 REST auth + SourceDB sharding |
| 10.6 | centralize-api (NestJS) REST + Swagger | 17 endpoints, DTOs, @Public bypass, /docs |
| 10.7 | Error model — 3 services เทียบกัน | error code catalog, HTTP status, frontend จัดการอย่างไร |
| 10.8 | File upload & download + PDF generation | Upload scalar vs multer, qpdf-encrypted PDF |
| 10.9 | Forward/proxy pattern | vtrc-api → cu-central-api อย่างไร, retry 3 ครั้ง |
| 10.10 | Scorecard + ปัญหา API surface | auth coverage, schema typos, hardcoded keys |
คำแนะนำการใช้งาน
ตอนเขียน frontend ใหม่
- เช็ค บท 10.2 ว่าต้องส่ง header อะไร
- ค้นหา query/mutation ที่ต้องการใน บท 10.3 (vtrc-api) หรือ บท 10.5 (cu-central-api)
- ดู signature + return type แล้วเขียน code
ตอน debug API
- ดู บท 10.7 ว่า error code ที่ได้หมายความว่าอะไร
- ถ้าเป็น forward → ดู บท 10.9 ว่า retry ทำงานอย่างไร
- ถ้าเป็น file → ดู บท 10.8
ตอนเพิ่ม endpoint ใหม่
- ดู pattern ของ service นั้นในบทที่เกี่ยวข้อง
- ใช้ helper ที่มีอยู่ (
responError,GraphqlCDWithToken,@Public(), ...) - อย่าลืมเพิ่มใน
routes.js,typeDefs/index.js, หรือ controller ตามระบบ
หมายเหตุเรื่อง path notation
ทุก file:line reference ในเล่มนี้ใช้ path relative จาก src/ ของแต่ละ service:
| Service | Base path |
|---|---|
| vtrc-api | vtrc-api/api/src/ |
| cu-central-api | cu-central-api/main-api/src/ |
| centralize-api | centralize-api/src/ |
ตัวอย่าง: typeDefs/root.js:4 ในบท vtrc-api หมายถึง vtrc-api/api/src/typeDefs/root.js บรรทัดที่ 4