REST API 규칙

REST API

 

지금 백엔드 API를 개발하다 보면 기존 코드들을 많이 참고하고 있는데 기존 코드들에서 일정한 패턴이나 규칙이 반복되는 것을 발견하게 된다.

처음에는 API 엔드포인트나 네이밍을 자유롭게 정해도 되는지 의문이 들었지만 실제로는 명확한 규칙이 존재한다.

그래서 REST API의 네이밍과 설계 규칙에 대해 정리해보려고 한다.

---

✅REST API ?

 

REST는 HTTP 웹의 창시자 중 한 사람인 Roy Fielding의 2000년 논문에 의해서 소개되었다.

웹의 장점을 최대한 활용할 수 있는 네트워크 기반의 아키텍쳐를 소개했는데 그것이 바로 REpresentational State Transfer 이다.

API는 Application Programming Interface의 약자고 서로 다른 시스템이 통신할 수 있게 해주는 인터페이스를 의미한다.

 

즉 REST API는 REST 원칙을 따르는 API  = 웹의 자원을 HTTP 프로토콜을 통해 일관성 있게 관리하고 조작할 수 있는 규칙을 의미한다.

 

---

 

 

☑️ REST API 요소

REST의 요소로는 크게 리소스, 메서드, 메세지 이렇게 3가지 요소로 구성된다.

 

📦리소스(Resource)

리소스는 서버에서 관리하는 대상을 의미한다.

예를 들어 사용자, 게시글, 상품 등이 있다.

각각의 리소스는 고유한 URI(주소)로 식별된다.

 

/users : 전체 사용자 목록이라는 리소스
/users/1 : 1번 사용자를 의미하는 리소스

 

 

 

🛠️ 메서드(Method)

메서드는 리소스에 대해 어떤 행위(동작)를 할 것인지 나타낸다.

HTTP 프로토콜의 표준 메서드를 사용한다.

REST에서는 CRUD(Create, Read, Update, Delete)에 해당하는 4가지의 메서드인

POST, GET, PUT, DELETE만 사용한다.

 

GET : 리소스를 조회할 때 사용
GET /users/1 → 1번 사용자 정보 조회

POST : 리소스를 새로 만들 때 사용
POST /users → 새 사용자 생성

PUT : 리소스를 수정할 때 사용
PUT /users/1 → 1번 사용자 정보 수정

DELETE : 리소스를 삭제할 때 사용
DELETE /users/1 → 1번 사용자 삭제

 

 

📩 메시지(Message)

메시지는 요청(Request)과 응답(Response)의 데이터 형식이다.

리소스와 메서드를 실제로 전달하고, 결과를 주고받는 실질적인 내용이다.

일반적으로 JSON 형식을 사용한다.(가끔 XML..?)

 

POST /users

Request Body (JSON)
{
    "name": "홍길동",
    "email": "hong@gildong.com"
}

Response Body (JSON)
{
    "id": 1,
    "name": "홍길동",
    "email": "hong@gildong.com"
}

 

 

---

 

 

🧬 REST API 특성

 

유니폼 인터페이스(Uniform Interface)

REST는 HTTP 표준만 따른다면 어떠한 언어나 기술에서도 구현할 수 있는 아키텍처 스타일이다.
HTTP와 JSON을 조합해 REST API를 만들면
안드로이드, iOS, C, Java, Python 등 HTTP와 JSON을 지원하는 모든 플랫폼에서 사용할 수 있다.
즉, 특정 언어나 프레임워크에 종속되지 않고 다양한 환경에서 호환성과 확장성을 갖춘 구조가 된다.

 

 

무상태성 / Stateless

REST의 중요한 특징 중 하나는 Stateless(무상태성)이다.
Stateless란 사용자나 클라이언트의 상태 정보를 서버에 저장하지 않는다는 의미다.
즉, 서버는 각 요청을 서로 독립적인 것으로 취급하며,
HTTP 세션 등 별도의 컨텍스트 저장소에 상태를 저장하지 않는다.

이로 인해

• 각 API 서버는 들어오는 요청 자체만 처리하면 되고
• 세션 등 컨텍스트 정보를 관리할 필요가 없으므로
• 구현이 단순하고 서버 확장(스케일 아웃)도 용이해진다.

예를 들어 사용자가 로그인한 뒤 정보를 요청할 때

서버가 세션을 저장하지 않는 REST 구조에서는 매 요청마다 토큰(JWT)등을 함께 보내서 인증해야 한다.

1. 사용자가 로그인 → 서버에서 JWT 토큰 발급

2. 이후 API 요청 시, 매번 Authorization 헤더에 토큰을 포함해서 전송

3. 서버는 세션 없이, 요청에 담긴 토큰 정보만으로 사용자 식별

 

이렇게 되면 서버는 사용자의 로그인 상태나 정보를 별도로 기억하지 않고, 매 요청마다 전달되는 데이터만으로 처리를 한다.

서버가 클라이언트의 상태를 저장하지 않기 때문에 여러대의 서버가 있어도 아무 서버나 요청을 받아서 처리할 수 있다.

서버에서 세션, 컨텍스트 등 별도 저장소를 관리하지 않으니 구현이 단순해진다.

마찬가지로 서버에 저장된 세션 정보가 없으므로 서버를 재시작하거나 교체해도 영향이 적어지며 유지보수가 간편해진다.

 

 

캐싱 가능 / Cacheable

REST의 특징 중 하나는 캐싱(Cacheable) 기능을 활용할 수 있다는 점이다. REST는 HTTP 표준을 사용하므로

기존 웹 인프라(로드 밸런서, SSL, 웹 캐시 서버 등)를 그대로 활용할 수 있다.

특히 서비스 트랜잭션의 대부분이 데이터 조회(Select)인 점을 고려하면 HTTP 캐싱을 적용하면 서버 부하 감소와 응답 속도 개선 등 큰 이점이 있다.

 

HTTP의 Last-Modified나 E-Tag 헤더를 사용하면 캐싱이 가능하다.
예를 들어, 클라이언트가 GET 요청 시 “Last-Modified” 값을 보내고 서버에 변경 사항이 없다면 304 Not Modified 응답을 보내,
클라이언트는 저장된 캐시 데이터를 재사용할 수 있다.

 

 

클라이언트 - 서버 구조 

클라이언트는 UI를 담당하고 서버는 데이터 저장과 비즈니스 로직(처리)를 담당하게 된다.

둘의 역할이 명확하게 분리되어 있기 때문에 클라이언트와 서버가 독립적으로 개발 및 배포가 가능하다.

UI를 바꿔도 서버에는 영향이 없고 서버 로직을 바꿔도 클라이언트에는 영향이 없다.

모바일, 웹 등 다양한 플랫폼에서 동일한 서버 API를 사용할 수 있다.

 

 

계층화 구조 / Layered System

클라이언트와 서버 사이에 여러 계층(중간 서버, 프록시, 게이트웨이 등등)을 둘 수 있다.

클라이언트는 오직 최종 서버만을 상대한다고 생각하지만 실제로는 여러 중간 계층을 거칠 수 있다.

 

이렇게 되면 중간 서버에서 보안 처리인 접근 제어, 인증 처리가 가능하고

트래픽을 여러 서버에 분산시킬수도 있으며 캐싱을 통해 프록시 서버가 데이터를 미리 저장해서 빠른 응답을 제공할 수도 있다.

예를 들어 Reverse Proxy(Nginx, Apache 등)에서 SSL인증, 캐싱 처리 후 백엔드로 요청을 전달할 수도 있다.

 

 

---

📜 REST API 규칙

 

이런 REST API를 설계할 때에는 대표적인 규칙이 있다.

 

 

1. 리소스(Resource)는 명사로 표현, URI는 복수형 사용

/users, /orders, /products 처럼 대상을 명사로 표현해야 한다.

또한 리소스는 대부분 복수형으로 작성한다.

ex) /user X → /users O

 

 

2. 행위(동사)는 HTTP 메서드로 표현

조회 = GET, 생성 = POST, 수정 = PUT/PATCH, 삭제 = DELETE 를 사용한다

URI에는 동사를 쓰지 않는다.

ex) /users/getAll X → /users + GET요청

 

 

3. 계층 구조는 URI로 명확히 표현

데이터(리소스)는 보통 상위/하위 관계(계층)을 가진다.

ex) 한 회사에는 여러 직원이 있고, 한 유저에게 여러 주문이 있다.

 

이런 경우 상위 리소스와 하위 리소스의 관계를 URI경로로 직접 드러내서 작성한다.

 

1번 유저가 가진 주문 목록은 → /users/1/orders

1번 유저의 100번째 주문 → /users/1/orders/100

123번 회사의 456번 직원 → /companies/123/employees/456

 

이렇게 되면 리소스 간의 소속 관계가 명확하게 드러나기 때문에 URI만 보고도 데이터 구조와 관계를 쉽게 파악할 수 있다.

 

 

 

4. 쿼리 파라미터는 리소스의 필터/정렬/검색 등에 사용

쿼리 파라미터란 URI에서 ? 뒤에 붙는 key=value 형식이다.

REST에서는 리소스의 세부 조건(검색,필터링,정렬,페이징 등)을 지정할 때 주로 사용된다.

 

필터링 = 전체 사용자 중에서 role이 admin인 사용자 조회

/users?role=admin 

 

정렬 = 상품을 가격 내림차순으로 정렬 조회

/products?sort=price_desc

 

검색 = REST라는 키워드가 들어간 게시글 검색

/posts?query=REST

 

페이징 = 2번째 페이지, 20개씩 보기

/users?page=2&size=20

 

이렇게 URI 경로는 변경하지 않으면서 요청 결과만 조건에 맞게 세분화가 가능하다.

여러 파라미터를 &로 조합하기도 한다.

또한 쿼리 파라미터는 상태 변화(POST/DELETE/PUT/PATCH)에 사용하는 것은 권장되지 않고

주로 GET요청에서 사용한다.

 

 

 

5. 일관된 응답 형식(주로 JSON)과 상태코드 사용

응답은 보통 JSON을 사용하며

상태코드는 HTTP표준을 사용한다.

200, 201, 204, 400, 404, 500 등등...

 

 

---

 

이렇게 REST API는 단순히 서버와 클라이언트가 데이터를 주고받는 수단이 아니라

명확한 원칙과 규칙을 바탕으로 누구나 이해하기 쉬운 일관된 구조를 제공하는 것이 큰 장점이다.

규칙에 따라 잘 설계된 REST API는 유지보수가 쉽고, 확장과 재사용이 자유롭고, 다양한 플랫폼과 연동도 훨씬 수월하다.

 

처음엔 아무것도 모르고 REST API 만들었지만.. 이제는 조금이나마 알았으니 다음에 만들땐 좀 더 신경을 쓰면서 만들거 같다!