๋ณธ๋ฌธ ๋ฐ”๋กœ๊ฐ€๊ธฐ
Front-end/Browser

REST API ๊ธฐ๋ณธ ์ •๋ฆฌ

by ciocio 2021. 9. 8.

๐Ÿ“Œ  REST๋ž€ (REpresentational State Transfer)?

 

HTTP๋ฅผ ๊ธฐ๋ฐ˜์œผ๋กœ ํด๋ผ์ด์–ธํŠธ๊ฐ€ ์„œ๋ฒ„์˜ ๋ฆฌ์†Œ์Šค์— ์ ‘๊ทผํ•˜๋Š” ๋ฐฉ์‹์„ ๊ทœ์ •ํ•œ ์•„ํ‚คํ…์ฒ˜.


๐Ÿ  REST ํŠน์ง•

 

๋”๋ณด๊ธฐ

โ—พ  Uniform

 

URI๋กœ ์ง€์ •ํ•œ ๋ฆฌ์†Œ์Šค์— ๋Œ€ํ•œ ์กฐ์ž‘์„ ํ•œ์ •์ ์ด๊ณ  ํ†ต์ผ๋œ ์ธํ„ฐํŽ˜์ด์Šค๋กœ ์ˆ˜ํ–‰ํ•˜๋Š” ์•„ํ‚คํ…์ณ๋‹ค.

-->  REST๊ฐ€ ์ง€์ •ํ•œ API๋Œ€๋กœ๋งŒ ์กฐ์ž‘ํ•˜๊ฒŒ ํ•˜๋‹ˆ๊นŒ !

 

โ—พ  Stateless

 

์ž‘์—…์„ ์œ„ํ•œ ์ƒํƒœ ์ •๋ณด๋ฅผ ์ €์žฅํ•˜๊ฑฐ๋‚˜ ๊ด€๋ฆฌํ•˜์ง€ ์•Š์Šต๋‹ˆ๋‹ค.

API server๋Š” ๋“ค์–ด์˜ค๋Š” ์š”์ฒญ๋งŒ ์ฒ˜๋ฆฌํ•˜๋ฉด ๋˜๊ธฐ ๋•Œ๋ฌธ์— ์„œ๋น„์Šค์˜ ์ž์œ ๋„๊ฐ€ ๋†’์•„์ง€๊ณ  ๊ตฌํ˜„์ด ๋‹จ์ˆœํ•ด์ง„๋‹ค.

-->  ์š”์ฒญ๋งŒ ๋‹จ์ˆœํ•˜๊ฒŒ ์ฒ˜๋ฆฌ !

 

โ—พ  Cacheable

 

REST๋Š” HTTP๋ผ๋Š” ๊ธฐ์กด ์›น ํ‘œ์ค€์„ ๊ทธ๋Œ€๋กœ ์‚ฌ์šฉํ•˜๊ธฐ ๋•Œ๋ฌธ์— ์›น์—์„œ ์‚ฌ์šฉํ•˜๋Š” ๊ธฐ์กด ์ธํ”„๋ผ๋ฅผ ํ™œ์šฉํ•  ์ˆ˜ ์žˆ๋‹ค.

๋”ฐ๋ผ์„œ, HTTP๊ฐ€ ๊ฐ€์ง„ ์บ์‹ฑ ๊ธฐ๋Šฅ์„ ์ ์šฉํ•  ์ˆ˜ ์žˆ๋‹ค.

-->  Last-Modified Tag / E-Tag ํ™œ์šฉ๊ฐ€๋Šฅ !

 

โ—พ  Self-descriptiveness

 

REST API๋งŒ ๋ณด๋”๋ผ๋„ HTTP ์š”์ฒญ์˜ ๋‚ด์šฉ์„ ์ดํ•ดํ•  ์ˆ˜ ์žˆ๋‹ค.

 

โ—พ  Client-Server ๊ตฌ์กฐ

 

์„œ๋ฒ„๋Š” API๋งŒ ์ œ๊ณตํ•˜๊ณ 

ํด๋ผ์ด์–ธํŠธ๋Š” ์‚ฌ์šฉ์ž ์ธ์ฆ์ด๋‚˜ context (๋กœ๊ทธ์ธ ์ •๋ณด, ์„ธ์…˜)๋งŒ ๊ด€๋ฆฌํ•˜๊ฒŒ ๋˜๋ฏ€๋กœ ๊ฐ์ž์˜ ์—ญํ• ์ด ํ™•์‹คํ•˜๊ฒŒ ๊ตฌ๋ถ„๋˜์—ˆ๋‹ค.

๊ณ  ํ•˜๋Š”๋ฐ ์ด ๋‚ด์šฉ์€ ๋” ๊ณต๋ถ€ํ•ด๋ด์•ผ๊ฒ ๋‹ค

 

โ—พ  hierarchical ๊ตฌ์กฐ

 

REST๋ฅผ ์ด์šฉํ•ด ๋‹ค์ค‘ ๊ณ„์ธต์˜ ์„œ๋ฒ„๋ฅผ ๊ตฌ์ถ•ํ•  ์ˆ˜ ์žˆ๋‹ค.

๋ณด์•ˆ, ๋กœ๋“œ ๋ฐธ๋Ÿฐ์‹ฑ, ์•”ํ˜ธํ™” ๊ณ„์ธต์„ ์ถ”๊ฐ€ํ•ด ๊ตฌ์กฐ์ƒ์˜ ์œ ์—ฐ์„ฑ์„ ๋‘˜ ์ˆ˜ ์žˆ๊ณ 

PROXY๋‚˜ ๊ฒŒ์ดํŠธ ์›จ์ด ๊ฐ™์€ ๋„คํŠธ์›Œํฌ ๊ธฐ๋ฐ˜์˜ ์ค‘๊ฐ„ ๋งค์ฒด๋„ ํ™œ์šฉํ•  ์ˆ˜ ์žˆ๋‹ค.

์•„์ง ๋ฌด์Šจ ๋ง์ธ์ง€ ๋ชจ๋ฅด๊ฒ ๋‹ค

 

 

๐Ÿ“Œ  REST API๋ž€?

 

REST๋ฅผ ๊ธฐ๋ฐ˜์œผ๋กœ ์„œ๋น„์Šค API๋ฅผ ๊ตฌํ˜„ํ•œ ๊ฒƒ.

 

REST API์˜ ๊ตฌ์„ฑ ์š”์†Œ 3๊ฐ€์ง€

โœ”  ์ž์› (resource)
โœ”  ํ–‰์œ„ (verb)
โœ”  ํ‘œํ˜„ (representation)

๐Ÿ  ์„ค๊ณ„ ์›์น™

 

โ—พ  URI๋Š” ๋ฆฌ์†Œ์Šค(์ž์›)๋ฅผ ํ‘œํ˜„ํ•ด์•ผ ํ•œ๋‹ค.

 

#bad
GET /get Todos/1

#good
GET /todos/1

 

URI๋Š” ๋ฆฌ์†Œ์Šค๋ฅผ ํ‘œํ˜„ํ•˜๋Š” ๋ฐ ์ค‘์ ์„ ๋‘ฌ์•ผํ•˜๊ธฐ ๋•Œ๋ฌธ์—, ๋™์‚ฌ๋ณด๋‹ค๋Š” ๋ช…์‚ฌ๋กœ ์ด๋ฆ„์„ ์„ค์ •ํ•ด์•ผ ํ•œ๋‹ค. ( ๋ช…๋ น์–ด๋Š” out! out! )

 

 

โ—พ  ๋ฆฌ์†Œ์Šค(์ž์›)์— ๋Œ€ํ•œ ํ–‰์œ„๋Š” HTTP ์š”์ฒญ ๋ฉ”์„œ๋“œ๋กœ ํ‘œํ˜„ํ•œ๋‹ค.

 

#bad
GET /todos/delete/1

#good
DELETE /todos/1

 

๋ฆฌ์†Œ์Šค์— ๋Œ€ํ•œ ํ–‰์œ„๋Š” HTTP ์š”์ฒญ ๋ฉ”์„œ๋“œ๋ฅผ ํ†ตํ•ด ํ‘œํ˜„ํ•˜๋ฉฐ URI์— ํ‘œํ˜„ํ•˜์ง€ ์•Š๋Š”๋‹ค.

HTTP ์š”์ฒญ ๋ฉ”์„œ๋“œ๋Š” GET, POST, PATCH, DELETE ๋“ฑ์„ ์‚ฌ์šฉํ•œ๋‹ค.

 

 

๐Ÿ“   HTTP ์š”์ฒญ ๋ฉ”์„œ๋“œ (์ผ๋ถ€)      REST API ๊ทœ์น™

 

GET

ํŠน์ • ๋ฆฌ์†Œ์Šค๋ฅผ ์กฐํšŒ๋งŒ ํ•œ๋‹ค.

 

POST

ํŠน์ • ๋ฆฌ์†Œ์Šค๋ฅผ ์ƒ์„ฑํ•œ๋‹ค.

 

PUT

์›ํ•˜๋Š” ๋ฐ์ดํ„ฐ๋กœ ํŠน์ • ๋ฆฌ์†Œ์Šค ์ „์ฒด๋ฅผ ์ˆ˜์ •ํ•œ๋‹ค.

 

PATCH

์›ํ•˜๋Š” ๋ฐ์ดํ„ฐ๋กœ ํŠน์ • ๋ฆฌ์†Œ์Šค ์ผ๋ถ€๋ฅผ ์ˆ˜์ •ํ•œ๋‹ค.

 

DELETE

ํŠน์ • ๋ฆฌ์†Œ์Šค๋ฅผ ์‚ญ์ œํ•œ๋‹ค.

 

 

๐Ÿ“   PUT๊ณผ PATCH์˜ ์ฐจ์ด

 

์–ธ๋œป๋ณด๋ฉด ์‘ ์ „์ฒด์™€ ์ผ๋ถ€ ~ ํ•˜๋ฉด์„œ ๋„˜์–ด๊ฐˆ ์ˆ˜ ์žˆ์ง€๋งŒ ์˜ˆ์‹œ๋ฅผ ๋ณด๋ฉด ์ญ ? ์Šค๋Ÿฝ๋‹ค.

๋™์ผํ•œ body์˜ ์š”์ฒญ์„ ๋ณด๋‚ด๋ฉด ๋˜‘๊ฐ™์€ ๊ฒฐ๊ณผ๊ฐ€ ๋‚˜์˜ค๊ธฐ ๋•Œ๋ฌธ์ด๋‹ค.

 

 

ํ•˜์ง€๋งŒ body๊ฐ€ ๋ชจ๋“  data๋ฅผ ํฌํ•จํ•˜์ง€ ์•Š์•˜์„ ๋•Œ, ๋‘˜์˜ ์ฐจ์ด์ ์ด ์ƒ๊ธด๋‹ค.

PUT์€ ์ •๋ง ์ „์ฒด๋ฅผ ์ˆ˜์ •ํ•˜๊ธฐ ๋•Œ๋ฌธ์— ์กด์žฌํ•˜์ง€ ์•Š๋Š” ํ‚ค ๊ฐ’์— ๋Œ€ํ•ด์„œ๋Š” null ์ฒ˜๋ฆฌ๋ฅผ ํ•˜๊ณ ,

PATCH๋Š” ๋ถ€๋ถ„์„ ์ˆ˜์ •ํ•˜๊ธฐ ๋•Œ๋ฌธ์— ์กด์žฌํ•˜์ง€ ์•Š๋Š” ํ‚ค ๊ฐ’์€ ๊ฑด๋“œ๋ฆฌ์ง€ ์•Š๋Š”๋‹ค.

 

 

 

๐Ÿ“Œ  HTTP ์ƒํƒœ ๋ฉ”์„ธ์ง€ (Status Codes)

 

200 - OK

์š”์ฒญ ์ˆ˜ํ–‰ ์™„๋ฃŒ ๐Ÿ˜‰

 

201 - CREATED

๋ฆฌ์†Œ์Šค ์ƒ์„ฑ ์š”์ฒญ ์ˆ˜ํ–‰ ์™„๋ฃŒ (์ƒ์„ฑ๋˜์—ˆ์Šต๋‹ˆ๋‹ค๐Ÿ˜‰)

 

204 - NO CONTENT

๋ฆฌ์†Œ์Šค ์‚ญ์ œ ์š”์ฒญ ์ˆ˜ํ–‰ ์™„๋ฃŒ (์‚ญ์ œ๋˜์—ˆ์Šต๋‹ˆ๋‹ค๐Ÿ˜‰)

 

304 - NOT MODIFIED

์š”์ฒญ์ด ์ด๋ฏธ ์บ์‰ฌ๋˜์–ด ์žˆ๋Š” ๊ฒฝ์šฐ && ์š”์ฒญ ๋ฐ์ดํ„ฐ๊ฐ€ ๋ณ€๊ฒฝ๋˜์ง€ ์•Š์•˜์„ ๊ฒฝ์šฐ

์š”์ฒญํ•˜๋Š” ์ •๋ณด๋ฅผ ์ด๋ฏธ ๋””์Šคํฌ์— ๊ฐ€์ง€๊ณ  ์žˆ์„ ๊ฒฝ์šฐ์— (์บ์‹œ๋˜์–ด ์žˆ๋Š” ๊ฒฝ์šฐ)

๋ธŒ๋ผ์šฐ์ €๋Š” ์ด ๋ฐ์ดํ„ฐ๊ฐ€ ๋ณ€๊ฒฝ๋˜์—ˆ๋Š”์ง€ ์—ฌ๋ถ€๋ฅผ ํ™•์ธํ•˜๋Š” ์š”์ฒญ์„ ๋ณด๋‚ธ๋‹ค.  -->  Conditional Get Request

์„œ๋ฒ„๋Š” ์š”์ฒญ ๋ฐ์ดํ„ฐ๊ฐ€ ๋ณ€๊ฒฝ๋˜์ง€ ์•Š์•˜์„ ๊ฒฝ์šฐ 304๋ฅผ ๋ฆฌํ„ดํ•˜๊ณ , ๋ณ€๊ฒฝ๋˜์—ˆ์„ ๊ฒฝ์šฐ ๋ณ€๊ฒฝ๋œ ๋ฐ์ดํ„ฐ๋กœ ์‘๋‹ต์„ ๋ณด๋‚ธ๋‹ค.

 

400 - BAD REQUEST

์‚๋น… ์š”์ฒญ์ด ๋ถ€์ ์ ˆํ–ˆ๊ฑฐ๋‚˜, ๋“ค์–ด์ค„ ์ˆ˜ ์—†๋Š” ์š”์ฒญ์ผ ๊ฒฝ์šฐ

 

401 - UNATHORIZED

์‚๋น… ํ•ด๋‹น ์š”์ฒญ์„ ํ•˜๋ ค๋ฉด ์‚ฌ์šฉ์ž ์ธ์ฆ์ด ํ•„์š”ํ•ฉ๋‹ˆ๋‹ค

 

403 - FORBIDDEN

์‚๋น… ํ•ด๋‹น ์š”์ฒญ์— ๋Œ€ํ•œ ์‘๋‹ต์€ ์žˆ๋Š”๋ฐ ์ ‘๊ทผํ•  ์ˆ˜ ์—†๊ธฐ ๋•Œ๋ฌธ์— ๊ฑฐ์ ˆํ•ฉ๋‹ˆ๋‹ค

์ด ๊ฒฝ์šฐ๋Š” ํ•ด๋‹น ๋ฆฌ์†Œ์Šค๊ฐ€ ์กด์žฌํ•œ๋‹ค๋Š” ๊ฑธ ์•Œ๋ฆฌ๋Š” ์—๋Ÿฌ์ด๊ธฐ ๋•Œ๋ฌธ์— 400์ด๋‚˜ 404๋ฅผ ์‚ฌ์šฉํ•  ๊ฒƒ์„ ๊ถŒ์žฅ.

 

404 - NOT FOUND

์‚๋น… ํ•ด๋‹น ์š”์ฒญ์˜ ๋ฆฌ์†Œ์Šค๋ฅผ ์ฐพ์„ ์ˆ˜ ์—†์Šต๋‹ˆ๋‹ค

 

500 - INTERNAL SERVER ERROR

์‚๋น… ์„œ๋ฒ„์— ๋ฌธ์ œ๊ฐ€ ์žˆ์Šต๋‹ˆ๋‹ค

API ๊ฐœ๋ฐœ์ž๋“ค์€ ์ด ๋ฌธ์ œ๋ฅผ ํ•„ํžˆ ํ”ผํ•ด์•ผํ•ฉ๋‹ˆ๋‹ค.

 

 

์ฐธ๊ณ  ๋ฌธ์„œ

Conditional GET Request

REST API ๊ทœ์น™

 

5 Basic REST API Design Guidelines

As soon as we start working on an API, design issues arise. Robust and strong design is a key factor for API success. A poorly designed API will indeed lead to misuse or – even worse – no use at all by its intended clients: application developers. Crea

blog.restcase.com

 

๋ฐ˜์‘ํ˜•

๋Œ“๊ธ€