API First Design

API First Design

ํ”„๋ก ํŠธ์—”๋“œ์™€ ๋ฐฑ์—”๋“œ๊ฐ€ API ์„ค๊ณ„๋ฅผ ๊ฐ€์žฅ ๋จผ์ € ํ•จ๊ป˜ ์ง„ํ–‰ํ•˜๊ณ , ํ•ด๋‹น API๋ฅผ ์ค‘์‹ฌ์œผ๋กœ ์‹œ์Šคํ…œ์„ ๊ตฌ์ถ•ํ•ด ๋‚˜๊ฐ€๋Š” ๊ฐœ๋ฐœ ๋ฐฉ์‹

์ผ๋ฐ˜์ ์ธ ์„œ๋น„์Šค ๊ฐœ๋ฐœ ํ๋ฆ„์—์„œ์˜ ๋ฌธ์ œ

๊ธฐ์กด ์„œ๋น„์Šค ๊ฐœ๋ฐœ ๋ฐฉ์‹์€ ๋‹ค์Œ๊ณผ ๊ฐ™์€ ํ๋ฆ„์„ ๋”ฐ๋ฆ„

  1. ๋ฐฑ์—”๋“œ ๊ฐœ๋ฐœ์ž๊ฐ€ ๊ธฐํš์„œ๋ฅผ ๊ธฐ๋ฐ˜์œผ๋กœ API๋ฅผ ์„ค๊ณ„ํ•จ

    1. ๋ฐฑ์—”๋“œ๋Š” API ์„ค๊ณ„๊ณผ์ •์—์„œ ๋งŽ์€ ๊ณ ๋ฏผ ํ•„์š”

    2. ํ”„๋ก ํŠธ์—”๋“œ๋Š” ๋ฐฑ์—”๋“œ์˜ API ์„ค๊ณ„๊ฐ€ ๋๋‚  ๋•Œ๊นŒ์ง€ ๋Œ€๊ธฐํ•˜๊ฒŒ ๋จ.

    3. API๊ฐ€ ์ „๋‹ฌ๋˜์—ˆ์ง€๋งŒ, ์‹ค์ œ ํ™”๋ฉด ๊ตฌํ˜„ ๊ณผ์ •์—์„œ ๋ถˆ๋ช…ํ™•ํ•˜๊ฑฐ๋‚˜ ๋ˆ„๋ฝ๋œ ๋ถ€๋ถ„์ด ๋“œ๋Ÿฌ๋‚จ

    4. ๊ทธ ๊ฒฐ๊ณผ ๋‹ค์‹œ ๋ฐฑ์—”๋“œ์™€ ์ˆ˜์ • ํ˜‘์˜ โ†’ ์žฌ์ž‘์—… โ†’ ๋ฐ˜๋ณต, ์ปค๋ฎค๋‹ˆ์ผ€์ด์…˜ ๋น„์šฉ ์ฆ๊ฐ€

  2. ๋งŒ๋“ค์–ด์ง„ API๋ฅผ ํ”„๋ก ํŠธ์—”๋“œ๊ฐ€ ์ „๋‹ฌ ๋ฐ›์•„ ์–ด๋–ป๊ฒŒ API๋ฅผ ๋งคํ•‘ํ•˜๊ณ  ํ™œ์šฉํ• ์ง€ ๊ณ ๋ฏผ ํ›„ ์„ค๊ณ„

    1. ํ”„๋ก ํŠธ์—”๋“œ๋Š” ๋ช…์„ธ์— ๋งž์ง€ ์•Š๊ฑฐ๋‚˜ ๋ถ€์กฑํ•œ ๋ฐ์ดํ„ฐ๋ฅผ ์งœ์ง‘๊ธฐํ•˜๊ฑฐ๋‚˜ ๊ฐ€๊ณตํ•˜๋ฉด์„œ ๊ฐœ๋ฐœ์„ ์ง„ํ–‰ํ•˜๊ฒŒ ๋จ

    2. ์‹œ๊ฐ„์ด ์ง€๋‚ ์ˆ˜๋ก ํ”„๋ก ํŠธ์™€ ๋ฐฑ์—”๋“œ๋Š” ์„œ๋กœ ๋‹ค๋ฅธ ๋งฅ๋ฝ ์†์—์„œ ๊ฐœ๋ฐœ์„ ์ด์–ด๊ฐ€๊ฒŒ ๋˜๊ณ , ์œ ์ง€๋ณด์ˆ˜๋Š” ์ ์  ์–ด๋ ค์›Œ์ง

์žฅ์ 

  • ๋ณ‘๋ ฌ ๊ฐœ๋ฐœ ๊ฐ€๋Šฅ: ๋ฐฑ์—”๋“œ๊ฐ€ API๋ฅผ ๊ฐœ๋ฐœํ•˜๊ธฐ ์ „์—๋„, ํ”„๋ก ํŠธ๋Š” Mock API ๊ธฐ๋ฐ˜์œผ๋กœ ์ž‘์—…์„ ์‹œ์ž‘ํ•  ์ˆ˜ ์žˆ์Œ

  • ์ปค๋ฎค๋‹ˆ์ผ€์ด์…˜ ํšจ์œจํ™”: ์ดˆ๊ธฐ ์„ค๊ณ„๋ฅผ ํ•จ๊ป˜ ํ•˜๋ฏ€๋กœ ์ดํ›„ ๋ถˆํ•„์š”ํ•œ ํ˜‘์˜๊ฐ€ ์ค„์–ด๋“ฆ

    • ํ•จ๊ป˜ ๋งŒ๋“ค๊ฒŒ๋˜๋‹ˆ ๊ธฐ์ค€์ด ์ƒ๊ธฐ๊ณ  ์‹œ๊ฐ„์„ ์•„๋‚„์ˆ˜ ์žˆ๊ฒŒ๋จ

  • ํ”„๋ก ํŠธ์—”๋“œ ์ƒ์‚ฐ์„ฑ ํ–ฅ์ƒ: ์‹ค์ œ ํ™”๋ฉด ํ๋ฆ„์— ๋งž์ถ˜ API ์„ค๊ณ„๋กœ ์ถ”๊ฐ€ ๊ฐ€๊ณต ์—†์ด ๋ฐ”๋กœ ์‚ฌ์šฉ ๊ฐ€๋Šฅ

์ƒ๋Œ€์ ์œผ๋กœ ํ”„๋ก ํŠธ์—”๋“œ๊ฐ€ API๋ฅผ ์‚ฌ์šฉํ•ด์„œ ํ™”๋ฉด์„ ๊ตฌํ˜„ํ•˜๋‹ค๋ณด๋‹ˆ ์–ด๋–ค API๊ฐ€ ์–ด๋–ป๊ฒŒ ์“ฐ์ด๊ณ  ํ•„์š”ํ•œ์ง€ ์กฐ๊ธˆ ๋” ๋นจ๋ฆฌ ํŒŒ์•…ํ•˜๊ฑฐ๋‚˜ ์ž˜์•Œ๊ณ ์žˆ์„ ๊ฐ€๋Šฅ์„ฑ์ด ๋†’์Œ, ๊ทธ๋ž˜์„œ ๋จผ์ € ์ ๊ทน์ ์œผ๋กœ ์š”์ฒญํ•˜๊ฑฐ๋‚˜ ์กฐ์œจํ•ด์„œ ํ˜‘์˜ํ•˜๊ฒŒ๋จ

์ฃผ์˜ํ• ์ 

  • ์ฒ˜์Œ๋ถ€ํ„ฐ ์™„๋ฒฝํ•œ API๋ฅผ ์„ค๊ณ„ํ•˜๊ธฐ๋Š” ์–ด๋ ค์›€. ์‹ค๋ฌด์—์„œ๋Š” ๋ณ€๊ฒฝ์ด ์žฆ๊ธฐ ๋•Œ๋ฌธ์—, API๋Š” ์œ ์—ฐํ•˜๊ฒŒ ์œ ์ง€ํ•ด์•ผ ํ•จ

  • ๋ณ€๊ฒฝ ์‚ฌํ•ญ์— ๋Œ€ํ•œ ๊ธฐ๋ก๊ณผ ๊ณต์œ ๊ฐ€ ์ค‘์š”ํ•จ. ๋ช…์„ธ์˜ ์ด๋ ฅ ๊ด€๋ฆฌ๊ฐ€ ์—†์œผ๋ฉด, ์‹œ๊ฐ„์ด ์ง€๋‚œ ๋’ค์— ๋ณ€๊ฒฝ ๋งฅ๋ฝ์„ ์•Œ๊ธฐ ์–ด๋ ค์›€

    • ์ž๋™ ๋ฌธ์„œํ™” ๋ฐ ์ฝ”๋“œ ์ƒ์„ฑ ๋„๊ตฌ ์—ฐ๊ณ„ ๊ฐ€๋Šฅ: ์˜ˆ: OpenAPI โ†’ Swagger โ†’ ์ฝ”๋“œ ์ƒ์„ฑ

  • API ๋ช…์„ธ ๋ณ€๊ฒฝ ์‹œ ์ž๋™ ๋ฐ˜์˜ ์ฒด๊ณ„ ํ•„์š”. ๊ทธ๋ ‡์ง€ ์•Š์œผ๋ฉด ๋ฌธ์„œ์™€ ์‹ค์ œ ์ฝ”๋“œ๊ฐ€ ์–ด๊ธ‹๋‚  ์ˆ˜ ์žˆ์Œ

OpenAPI

RESTful API๋ฅผ ์ •์˜ํ•˜๊ธฐ ์œ„ํ•œ ๊ฐ€์žฅ ๋„๋ฆฌ ์‚ฌ์šฉ๋˜๋Š” ์ŠคํŽ™ ์ค‘ ํ•˜๋‚˜.

  • Swagger: OpenAPI ๊ธฐ๋ฐ˜์œผ๋กœ API ๋ช…์„ธ์„œ๋ฅผ ์‹œ๊ฐํ™”ํ•˜๊ณ  ํ…Œ์ŠคํŠธํ•  ์ˆ˜ ์žˆ๋Š” ๋„๊ตฌ

  • openapi-generator:

    • OpenAPI ๋ช…์„ธ๋ฅผ ๊ธฐ๋ฐ˜์œผ๋กœ ์‹ค์ œ API ํด๋ผ์ด์–ธํŠธ ์ฝ”๋“œ, ํƒ€์ž…, ๋ฌธ์„œ ๋“ฑ์„ ์ž๋™ ์ƒ์„ฑ

    • ๋ณ€๊ฒฝ์‚ฌํ•ญ์ด ๋ฐ˜์˜๋˜๋ฉด ์ฝ”๋“œ๋„ ์ž๋™์œผ๋กœ ์—…๋ฐ์ดํŠธ๋˜๋ฏ€๋กœ ์ƒ์‚ฐ์„ฑ๊ณผ ์ผ๊ด€์„ฑ ํ™•๋ณด ๊ฐ€๋Šฅ

Last updated