REST API

 

1. API란?

API는 Application Programming Interface의 약자이다.

여기서 중요한 건 Interface(인터페이스)라는 단어이다.

 

- 인터페이스(Interface)란?

인터페이스는 서로 소통하기 위한 접점을 의미한다.

예를 들어:

• TV ↔ 리모컨
• 자동차 ↔ 핸들

처럼 서로 연결해주는 중간 역할이다.

즉 API는 프로그램끼리 소통하기 위한 인터페이스라고 이해할 수 있다.

 

 

- API 예시

웹에서는:

app.js ↔ 백엔드 서버

사이에서 API를 통해 통신한다.

 

예를 들어:

fetch("/items")

를 실행하면:

• JavaScript가 서버에 요청
• 서버가 데이터 응답

하는 방식이다.

- API는 이해하기 쉽게 설계해야 한다

API는 단순히 동작만 하면 되는 것이 아니다. 예측 가능하고 이해하기 쉬워야 한다.

리모컨 예시처럼:

• "+" 버튼 → 음량 증가
• "-" 버튼 → 음량 감소

가 직관적이어야 하는 것처럼 API도 누구나 이해할 수 있어야 한다.

 

---

2. REST API란?

REST API는 REST 원칙을 기반으로 설계된 API이다.

REST는 API를 일관성 있게 만들기 위한 설계 원칙이라고 이해하면 쉽다.

- REST란?

REST는 Representational State Transfer의 약자이다.

쉽게 말하면 "예측 가능하게 API를 설계하자"라는 철학에 가깝다.

 

 

1) Representation (표현)

서버의 자원(Resource)을 클라이언트가 이해할 수 있는 형태로 표현하는 것이다.

대표 형태:

• JSON
• HTML
• 이미지

- 자원(Resource)이란?

서버가 관리하는 모든 데이터를 의미한다.

예시:

/items
/users
/posts

즉:

• 상품 목록
• 회원 목록
• 게시글 목록

같은 것들이 모두 자원이다.

 

2) State (상태)

자원의 현재 상태를 의미한다.

예시:

• 등록
• 수정
• 삭제

즉, 데이터가 지금 어떤 상태인지를 의미한다.

3) Transfer (전송)

클라이언트와 서버가 데이터를 주고받는 과정이다.

주로 HTTP 통신을 사용한다.

 

4) REST의 6가지 원칙

REST에는 여러 설계 원칙이 존재한다.

 

① 균일한 인터페이스 ★

가장 중요한 원칙 중 하나이다.

특징

• 모든 자원은 고유 URL 사용
• JSON 같은 형식 사용
• 요청/응답 구조가 일관적이어야 함

예시:

/items
/users
/posts

동사가 아니라 복수 명사 형태를 사용하는 것이 핵심이다.

② 클라이언트-서버 역할 분리

클라이언트:

• 화면
• 사용자 경험(UI/UX)

담당

 

서버:

• 데이터
• 비즈니스 로직

담당

 

즉, 역할을 분리해서 독립적으로 개발할 수 있게 만든다.

③ 무상태성(Stateless)

HTTP 특징을 그대로 따른다.

서버는 이전 요청 상태를 기억하지 않는다.

장점:

• 서버 확장 쉬움
• 사용자 많아져도 대응 가능

④ 주문형 코드(Code On Demand)

서버가 JavaScript 코드를 내려줄 수도 있다는 개념이다.

실무에서는 상대적으로 덜 언급된다고 한다.

⑤ 캐시 가능(Cacheable)

자주 바뀌지 않는 데이터는 임시 저장(Cache) 가능하다.

장점:

• 속도 향상
• 서버 부담 감소

⑥ 계층형 시스템

중간 서버를 추가해도 클라이언트가 몰라도 되게 설계한다.

예시:

• 보안 서버
• 프록시 서버
• 캐시 서버

---

- RESTful 이란?

REST 원칙을 잘 지킨 API를 RESTful 하다라고 표현한다.

 

- API 설계가 중요한 이유

백엔드 개발은 코딩 전에 설계가 굉장히 중요하다.

왜냐하면 API는 프론트엔드와 백엔드 사이의 계약서 역할을 하기 때문이다.

 

---

3. API 명세서란?

API 명세서는 API 사용 설명서 + 계약서 같은 개념이다.

프론트엔드 개발자는 명세서를 보고:

• 어떤 URL인지
• 어떤 데이터를 보내는지
• 어떤 응답이 오는지

를 미리 알 수 있다.

 

즉, 서로 기다리지 않고 동시에 개발 가능해진다.

 

1) REST API 설계 방법

REST API는 보통 다음 순서로 생각한다.

Who	누가 API를 사용하는가?	웹 브라우저, 모바일 앱, 프론트엔드
What	무엇을 다룰 것인가?	/items, /users, /posts
How	어떻게 처리할 것인가?	GET, POST, PUT, DELETE
Parameters	작업에 필요한 데이터는 무엇인가?	/items/123, Query, Body
Returns	어떤 결과를 반환할 것인가?	200 OK, JSON 데이터

 

Method의미

GET	조회(Read)
POST	생성(Create)
PUT	전체 수정(Update)
PATCH	일부 수정(Update)
DELETE	삭제(Delete)

Method + Endpoint 조합

예시:

GET /items

→ 상품 조회

POST /items

→ 상품 추가

---

4. 요청 데이터 전달 방식

1) Path Parameter

특정 데이터 식별용

/items/123

→ 123번 상품

2) Query Parameter

조건 검색용

/items?sort=new&page=2

특징:

• ? 로 시작
• & 로 연결

예시:

/search?keyword=새우깡

3) Body

실제 데이터를 전달할 때 사용한다.

주로:

• POST
• PUT
• PATCH

에서 사용

예시:

{
  "name": "새우깡",
  "price": 1500
}

4) 요청 헤더(Header)

추가 정보 전달용

대표 헤더:

Header의미

Content-Type	Body 데이터 형식
Authorization	인증 정보

5) 응답(Response) 구조

응답도:

• 상태 코드
• 헤더
• 본문

으로 구성된다.

-상태 코드(Status Code)

2xx 성공

200 OK	조회 성공
201 Created	생성 성공
204 No Content	삭제 성공

4xx 클라이언트 오류

400 Bad Request	잘못된 요청
401 Unauthorized	인증 실패
403 Forbidden	권한 없음
404 Not Found	주소 오류

5xx 서버 오류

500 Internal Server Error

서버 내부 오류

6) 응답 Body

서버는 처리 결과 데이터를 JSON으로 전달한다.

예시:

{
  "id": 1,
  "name": "새우깡",
  "price": 1500
}