AI

ACE AI SW Startup Training

API Design & Swagger Specification

Day 4 API Design & Swagger Specification ์˜์ƒ + AI ์ฑ—๋ด‡ ํ•™์Šต

API ์„ค๊ณ„ & Swagger ๋ช…์„ธ์„œ ์ž‘์„ฑ๊ณผ AI ํ•™์Šต๋„์šฐ๋ฏธ (Codex AI ์—ฐ๊ณ„)

ํ™”๋ฉด ์„ค๊ณ„, ์‚ฌ์šฉ์ž ํ๋ฆ„, ์‹œํ€€์Šค ๋‹ค์ด์–ด๊ทธ๋žจ, ๋ฐ์ดํ„ฐ ๊ตฌ์กฐ๋ฅผ ๋ฐ”ํƒ•์œผ๋กœ ์‹ค์ œ ์„œ๋น„์Šค ๊ธฐ๋Šฅ์„ API ํ˜•ํƒœ๋กœ ์ •์˜ํ•˜๊ณ , Swagger/OpenAPI ํ˜•์‹์˜ ๋ช…์„ธ์„œ๋กœ ๋ฌธ์„œํ™”ํ•˜๋Š” 4์ผ์ฐจ ํ•™์Šต ์ฝ˜ํ…์ธ ์ž…๋‹ˆ๋‹ค. ๋ณธ ์‹ค์Šต์—์„œ๋Š” Codex Client Workspace๋ฅผ ํ™œ์šฉํ•˜์—ฌ API ๊ณ„์•ฝ์„œ ์ž๋™ ์ƒ์„ฑ, ๊ธฐํš-API ์ •ํ•ฉ์„ฑ ์˜ค๋””ํŒ… ๋ฐ ์—๋Ÿฌ ํ•ธ๋“ค๋ง ์ ๊ฒ€, API ๋ณ€๋™ ์˜ํ–ฅ ๋ถ„์„ ๋ฐ ํ…Œ์ŠคํŠธ ์‹œ๋‚˜๋ฆฌ์˜ค ์ž์œจ ๋ฐœ๊ตด์„ ํฌํ•จํ•œ ๊ณ ๋„ํ™”๋œ ์‹ค๋ฌด ํ”„๋กœ์„ธ์Šค๋ฅผ ์ˆ˜ํ–‰ํ•ฉ๋‹ˆ๋‹ค.

๋Œ€์ƒ: ๋ฐ์ดํ„ฐ๋ฒ ์ด์Šค ์„ค๊ณ„(ERD)๋ฅผ ์™„๋ฃŒํ•œ ํ•™์ƒ
์ค€๋น„๋ฌผ: ๋…ธํŠธ๋ถ, Swagger Editor ๋˜๋Š” OpenAPI ํŽธ์ง‘ ๋„๊ตฌ
๊ตฌ์„ฑ: 2์‹œ๊ฐ„ ์ด๋ก  ๋ฐ API ๊ณ„์•ฝ์„œ ์ƒ์„ฑ / 3์‹œ๊ฐ„ API ์ •ํ•ฉ์„ฑ ์˜ค๋””ํŒ… ๋ฐ ์˜ํ–ฅ๋„ ๋ถ„์„ / 1์‹œ๊ฐ„ API ๋ฆฌ๋ทฐ ๋ฐ ํ…Œ์ŠคํŠธ ์‹œ๋‚˜๋ฆฌ์˜ค ์ž‘์„ฑ
๐Ÿ“– Session 4 ๊ต์•ˆ ๋ฐ”๋กœ๊ฐ€๊ธฐ

๐Ÿš€ Day 4 ์‹ค์Šต MVP Tasks ๋กœ๋“œ๋งต

์ „์ฒด Task ๋ณด๋“œ ๊ฐ€๊ธฐ โ†’
๐Ÿš€
Interactive Board

์‹ค์Šต Task ์ฒดํฌ๋ฆฌ์ŠคํŠธ

ํ•„์ˆ˜ ํƒœ์Šคํฌ์˜ ์ง„์ฒ™๋„๋ฅผ ๊ธฐ๋กํ•˜๊ณ  ์ƒ์„ธ ์‹ค์Šต ๊ฐ€์ด๋“œ๋ผ์ธ์„ ํ™•์ธํ•ด๋ณด์„ธ์š”.

๐Ÿ‘‰ ์ƒ์„ธ Task ๋ณด๋“œ ์ด๋™
TASK 1
AI Agent Task 1

Task 1. API ๊ณ„์•ฝ์„œ ์ƒ์„ฑ ์‹ค์Šต

ํ™”๋ฉด ๋ฐ DB ์ •์˜์„œ๋ฅผ ๊ธฐ๋ฐ˜์œผ๋กœ RESTful ๊ทœ์น™์˜ Request/Response API ๊ณ„์•ฝ์„œ๋ฅผ ์ž๋™ ๋„์ถœํ•ฉ๋‹ˆ๋‹ค.

์‹ค์Šต์‹ค ์ž…์žฅ
TASK 2
AI Agent Task 2

Task 2. API ๋ถˆ์ผ์น˜ ๊ฒ€์ถœ ์‹ค์Šต

๊ธฐํš์„œ, ํ™”๋ฉด์ •์˜์„œ, API ์ŠคํŽ™ ๋ฌธ์„œ ๊ฐ„์˜ ์ •ํ•ฉ์„ฑ์„ ๊ฒ€ํ† ํ•˜๊ณ  ๋ถˆ์ผ์น˜ ๋ณด๊ณ ์„œ๋ฅผ ๋„์ถœํ•ฉ๋‹ˆ๋‹ค.

์‹ค์Šต์‹ค ์ž…์žฅ
TASK 3
AI Agent Task 3

Task 3. API ๋ณ€๊ฒฝ ์˜ํ–ฅ ๋ถ„์„ ์‹ค์Šต

API ๊ณ„์•ฝ ํ•„๋“œ ๋ณ€๊ฒฝ ์‹œ ํ™”๋ฉด UI์™€ DB ๋ชจ๋ธ๋ง์˜ ์ข…์†์  ์—ฐ์‡„ ์˜ํ–ฅ ๋ฒ”์œ„๋ฅผ ์—ญ์ถ”๋ก ํ•ฉ๋‹ˆ๋‹ค.

์‹ค์Šต์‹ค ์ž…์žฅ
SKILL 1
Skill Task 1

Domain Boundary ๊ธฐ๋ฐ˜ Endpoint ์„ค๊ณ„

Video, Playback, Campaign, Ad Serving 4๊ฐœ Domain์˜ Endpoint์™€ URI๋ฅผ ์„ค๊ณ„ํ•ฉ๋‹ˆ๋‹ค.

์‹ค์Šต์‹ค ์ž…์žฅ
SKILL 2
Skill Task 2

Req/Res/Error Contract ์ž‘์„ฑ

์ž…์ถœ๋ ฅ Schema, Status Code, Error Contract๋ฅผ ์ •์˜ํ•˜๊ณ  OpenAPI 3.0 ๋ช…์„ธ๋ฅผ ์™„์„ฑํ•ฉ๋‹ˆ๋‹ค.

์‹ค์Šต์‹ค ์ž…์žฅ
SKILL 3
Skill Task 3

API Contract Consistency Review

API๊ฐ€ Sequence/ERD์™€ ์ผ์น˜ํ•˜๋Š”์ง€ ๊ฒ€ํ† ํ•˜๊ณ  Breaking Change ๋ฐ ๋ถ€์ • ํ…Œ์ŠคํŠธ ์ผ€์ด์Šค๋ฅผ ์ถ”์ถœํ•ฉ๋‹ˆ๋‹ค.

์‹ค์Šต์‹ค ์ž…์žฅ
MISSION 1
Mission 1

[๊ณผ์ œ] API ๋ฆฌ๋ทฐ ๋ฐ ๊ฐœ์„ 

REST API ํ‘œ์ค€ ๊ทœ๊ฒฉ, HTTP Status, RFC ํ‘œ์ค€ ์—๋Ÿฌ ์Šคํ‚ค๋งˆ ์ค€์ˆ˜ ํ’ˆ์งˆ์„ ๋ฆฌ๋ทฐํ•ฉ๋‹ˆ๋‹ค.

๊ณผ์ œ์‹ค ์ž…์žฅ
MISSION 2
Mission 2

[๊ณผ์ œ] API ํ…Œ์ŠคํŠธ ์‹œ๋‚˜๋ฆฌ์˜ค ์ƒ์„ฑ

์ •์ƒ ์ž‘๋™ ๋ฐ ํŒŒ๋ผ๋ฏธํ„ฐ ๋ˆ„๋ฝ, ๋‚ ์งœ ํ˜•์‹ ์˜ค๋ฅ˜ ๋“ฑ ๊ฒฝ๊ณ„๊ฐ’ ์˜ˆ์™ธ ํ…Œ์ŠคํŠธ ์ผ€์ด์Šค๋ฅผ ๋„์ถœํ•ฉ๋‹ˆ๋‹ค.

๊ณผ์ œ์‹ค ์ž…์žฅ
MISSION 3
Mission 3

[๊ณผ์ œ] ํ•€ํ…Œํฌ ์˜คํ”ˆ๋ฑ…ํ‚น API ๋ช…์„ธ

์˜คํ”ˆ๋ฑ…ํ‚น ๊ณ„์ขŒ ์กฐํšŒ ๋ฐ ์ด์ฒด API์˜ OpenAPI 3.0 YAML ์ŠคํŽ™๊ณผ OAuth2 ์—๋Ÿฌ ๊ทœ๊ฒฉ์„ ์ •์˜ํ•ฉ๋‹ˆ๋‹ค.

๊ณผ์ œ์‹ค ์ž…์žฅ
MISSION 4
Mission 4

[๊ณผ์ œ] ๋ฐฐ๋‹ฌ ์ฃผ๋ฌธ-๋ผ์ด๋” API Audit

๋ฐฐ๋‹ฌ ์ฃผ๋ฌธ ๋ฐ ๋ผ์ด๋” ๋งค์นญ API์˜ Sequence-ERD ์ •ํ•ฉ์„ฑ ๋ฐ Breaking Change ์—ฌ๋ถ€๋ฅผ ์˜ค๋””ํŒ…ํ•ฉ๋‹ˆ๋‹ค.

๊ณผ์ œ์‹ค ์ž…์žฅ

Day 4 ๊ฐ•์˜ ์˜์ƒ

์œ ํŠœ๋ธŒ ์ถ”์ฒœ ๊ฐ•์˜
Day 4 ์ปค๋ฆฌํ˜๋Ÿผ ํ•ต์‹ฌ ์ฃผ์ œ(API ์„ค๊ณ„, Request/Response, Endpoint, Swagger, OpenAPI)์— ํ•ด๋‹นํ•˜๋Š” ์œ ํŠœ๋ธŒ ์ถ”์ฒœ ๊ฐ•์˜ ๋ฆฌ์ŠคํŠธ์ž…๋‹ˆ๋‹ค. (์™ธ๋ถ€ ํผ๊ฐ€๊ธฐ ๋ฐ ์žฌ์ƒ์ด ํ—ˆ์šฉ๋œ ๋ฌด๋ฃŒ ๊ฐ•์˜ ์˜์ƒ์œผ๋กœ ๊ตฌ์„ฑ๋˜์—ˆ์Šต๋‹ˆ๋‹ค.)
๐Ÿ“š ์ „์ฒด ๊ฐ•์˜ ๋ชฉ๋ก (5๊ฐœ)
  • โ–ถ
    1. APIs for Beginners - Twilio
    4:13:00
  • โ–ถ
    2. Full HTTP Networking & REST API Course
    4:10:00
  • โ–ถ
    3. System Design Concepts and API Design
    5:15:30
  • โ–ถ
    4. REST API Design best practices
    2:30:15
  • โ–ถ
    5. Postman Tutorial for Beginners
    11:45

ํ•ต์‹ฌ ์š”์•ฝ ๋…ธํŠธ

Day 4 Summary

์˜ค๋Š˜์˜ ํ•ต์‹ฌ ๋ชฉํ‘œ

Day 4์—์„œ๋Š” ํ™”๋ฉด ์„ค๊ณ„, ์‚ฌ์šฉ์ž ํ๋ฆ„, ๋ฐ์ดํ„ฐ ๊ตฌ์กฐ๋ฅผ ๋ฐ”ํƒ•์œผ๋กœ ์‹ค์ œ ์„œ๋น„์Šค ๊ธฐ๋Šฅ์„ API ํ˜•ํƒœ๋กœ ์ •์˜ํ•˜๊ณ , Swagger/OpenAPI ํ˜•์‹์˜ ๋ช…์„ธ์„œ๋กœ ๋ฌธ์„œํ™”ํ•ฉ๋‹ˆ๋‹ค.

  • API ์—”๋“œํฌ์ธํŠธ ๋„์ถœ: ํ™”๋ฉด ์š”๊ตฌ์‚ฌํ•ญ ๊ธฐ๋ฐ˜ REST API ๋ฆฌ์†Œ์Šค ๋ฐ URI ์ •์˜
  • Request/Response ๊ทœ๊ฒฉ ์„ค๊ณ„: JSON ๊ตฌ์กฐ์˜ ์š”์ฒญ/์‘๋‹ต ํŽ˜์ด๋กœ๋“œ ์Šคํ‚ค๋งˆ ์ •์˜
  • HTTP ๋ฉ”์†Œ๋“œ ๋ฐ ์ƒํƒœ ์ฝ”๋“œ ์ •์˜: GET, POST, PUT, DELETE ๊ทœ์น™๊ณผ ์—๋Ÿฌ ์ฒ˜๋ฆฌ ๊ทœ๊ฒฉ ์„ค๊ณ„
  • Swagger/OpenAPI ๋ช…์„ธ ์ž‘์„ฑ: YAML/JSON ํ˜•์‹์„ ์ด์šฉํ•œ ๋ช…์„ธ์„œ ์ž‘์„ฑ ๊ธฐ๋ฒ• ์Šต๋“
  • ๊ฐœ๋ฐœ ์ธ์ˆ˜์ธ๊ณ„(Handoff) ๊ณ ๋ ค: ์˜ˆ์™ธ ์‘๋‹ต ์ฝ”๋“œ์™€ ์—๋Ÿฌ ๋ฉ”์‹œ์ง€ ์„ธ๋ถ€ํ™”
ํ•™์Šต ํŒ: ์˜ค๋ฅธ์ชฝ AI ์ฑ—๋ด‡์—๊ฒŒ โ€œRESTful API ์„ค๊ณ„์˜ ๊ธฐ๋ณธ ๊ทœ์น™์ด ๋ญ์•ผ?โ€ ๋˜๋Š” โ€œSwagger์—์„œ Request Body์™€ Path Parameter๋ฅผ ์–ด๋–ป๊ฒŒ ๋ช…์‹œํ•ด?โ€ ๊ฐ™์€ ์งˆ๋ฌธ์„ ํ•ด๋ณด์„ธ์š”.