REST API는 현대 웹 및 모바일 애플리케이션에서 데이터 통신을 위한 핵심 기술입니다. 단순하고 일관된 구조 덕분에 다양한 시스템과 쉽게 연동할 수 있으며, 확장성과 유지보수성 측면에서도 높은 평가를 받습니다. 이 글에서는 REST API의 개념과 핵심 설계 원칙, 그리고 실무에서 자주 사용하는 설계 예제를 함께 살펴봅니다.
REST API의 정의
REST(Representational State Transfer)는 웹의 기본 원칙에 따라 자원을 정의하고, 자원에 대한 행위를 명확하게 규정하는 아키텍처 스타일입니다. RESTful API는 이러한 REST 원칙을 따르는 API로, HTTP 프로토콜을 기반으로 자원(Resource)을 URI로 식별하고, 자원에 대한 행위는 HTTP 메서드(GET, POST, PUT, DELETE 등)로 표현합니다. 예를 들어 /users라는 URI는 사용자라는 자원을 의미하고, 여기에 GET을 요청하면 사용자 목록을 조회, POST는 사용자 생성, /users/1에 PUT은 사용자 정보 수정, DELETE는 삭제를 의미합니다. 이처럼 URI는 자원의 위치만 나타내고, 행위는 메서드로 분리하는 것이 REST API의 핵심입니다. REST API의 가장 큰 장점은 단순성과 일관성입니다. 클라이언트가 API의 작동 방식을 예측하기 쉬우며, 명확한 구조로 인해 문서화와 유지보수가 편리합니다. 또한 REST는 서버와 클라이언트의 완전한 분리를 가능하게 하여, 프런트엔드와 백엔드가 독립적으로 개발되고 배포될 수 있습니다. 이 외에도 REST는 무상태(Stateless)와 캐시 처리(Cacheable) 등의 특징을 갖고 있으며, 확장성과 성능 측면에서도 장점이 많아 현재 대부분의 웹 서비스에서 널리 채택되고 있습니다.
제가 사이드 프로젝트로 간단한 일정 관리 웹앱을 만들었을 때, 처음에는 백엔드에 단순히 /addSchedule, /deleteSchedule 같은 동사 기반 URI를 사용했어요. 그런데 클라이언트에서 어떤 기능이 어디 있는지 헷갈리기 시작했고, 문서화도 애매해졌죠.
이후 REST 원칙을 공부하고 /schedules, /schedules/{id}처럼 명사 중심으로 URI를 재설계하고, GET/POST/PUT/DELETE로 동작을 분리하니 훨씬 구조가 단순해지고 프런트 개발자와의 협업도 쉬워졌습니다.
RESTful 설계는 단순히 멋있어 보이기 위한 게 아니라, 진짜 협업 생산성을 높이는 구조라는 걸 실감했습니다.
REST API 설계 시 반드시 지켜야 할 원칙
RESTful API를 설계할 때는 단순히 HTTP 요청만 구현하는 것이 아니라, 일관성과 명확성을 보장하기 위해 몇 가지 핵심 설계 원칙을 지켜야 합니다. 첫째, 명사 기반의 URI 사용입니다. URI는 자원 자체를 표현하므로 동사보다는 명사를 사용해야 합니다. 예: GET /users (O), GET /getUsers (X) 둘째, HTTP 메서드의 역할을 명확히 구분해야 합니다. GET은 조회, POST는 생성, PUT은 전체 수정, PATCH는 일부 수정, DELETE는 삭제로 기능을 나누는 것이 원칙입니다. 셋째, HTTP 상태 코드를 정확히 반환해야 합니다. 예: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 500 Internal Server Error 등 넷째, 일관된 응답 포맷(JSON)을 유지하고, 오류 메시지나 결과 정보에는 message, code, data 등의 구조를 갖춘 표준화된 형태를 사용하는 것이 좋습니다. 다섯째, URI는 계층적 구조를 따르며 중복을 피해야 합니다. 예: /users/1/posts/3/comments 이러한 설계 원칙을 따르는 것은 API의 품질뿐 아니라, 협업의 효율성과 클라이언트 개발의 편의성을 극대화하는 중요한 기준이 됩니다.
지인이 다니는 스타트업에서는 초기에 빠르게 API를 개발하면서 /getUserInfo, /registerUser처럼 RPC 스타일로 만들었대요. 그런데 규모가 커지고 모바일 앱, 관리자 대시보드 등 여러 클라이언트가 붙으면서, API의 일관성 부족이 큰 문제가 되었죠.
결국 팀 전체가 참여하는 API 리팩토링을 통해 /users, /users/{id} 형태로 URI를 바꾸고, 응답 포맷도 JSON 구조로 code, message, data 형식으로 통일했어요.
그 결과 문서화가 훨씬 쉬워졌고, 외부 파트너 개발자도 쉽게 연동할 수 있는 구조가 되었다고 해요. REST 설계 원칙을 따르는 게 단지 기술의 ‘멋’이 아니라, 비즈니스 확장에도 실질적 도움이 된다는 사례죠.
실습 예제: 사용자 관리 API 설계하기
실제 REST API를 설계하고 구현하는 과정에서는 위에서 설명한 원칙들을 구체적인 코드와 패턴에 적용해야 합니다. 다음은 사용자(User) 자원에 대한 CRUD API를 설계하는 간단한 예제입니다.
- GET /users: 사용자 전체 조회
- POST /users: 사용자 등록
- GET /users/{id}: 특정 사용자 조회
- PUT /users/{id}: 사용자 수정
- DELETE /users/{id}: 사용자 삭제
응답 예시 (성공):
{
"code": 200,
"message": "사용자 조회 성공",
"data": {
"id": 1,
"name": "김철수",
"email": "kim@sample.com"
}
}
응답 예시 (오류):
{
"code": 400,
"message": "유효하지 않은 사용자 ID입니다."
}
Node.js Express 예제:
app.get('/users/:id', (req, res) => {
const userId = req.params.id;
res.status(200).json({
code: 200,
message: '사용자 조회 성공',
data: { id: userId, name: '김철수', email: 'kim@sample.com' }
});
});
API 설계 시 인증(Authentication)과 권한(Authorization)도 함께 고려해야 합니다. JWT 토큰 방식이나 OAuth2 같은 인증 시스템을 적용하여 API 접근을 제어해야 하며, 민감한 데이터는 HTTPS를 통해 암호화된 채널에서 주고받도록 설정해야 합니다. 또한, API 요청의 속도 제한(Rate Limiting), 입력값 검증(Validation), CORS 설정 등도 함께 구현하여 보안성과 안정성을 높여야 합니다.
REST API는 단순한 데이터 전송 도구가 아닌, 소프트웨어 구조와 협업의 기반이 되는 중요한 설계 요소입니다. 원칙에 맞게 일관되고 명확하게 API를 설계하면 개발 생산성과 서비스의 확장성까지 확보할 수 있습니다. 지금 진행 중인 프로젝트에 RESTful 설계를 적용해 보세요.
형이 운영하는 소규모 쇼핑몰에서 고객 정보, 주문 내역, 상품 등록 기능이 필요하다고 해서 제가 API를 직접 만들어 도와준 적이 있어요.
처음엔 단순하게 만들려고 했지만, /customers, /orders, /products처럼 RESTful 한 구조로 설계하고, 오류 응답도 일관된 JSON 구조로 제공했더니, 웹 개발자 아르바이트생이 클라이언트 앱을 훨씬 쉽게 붙일 수 있었어요.
특히 /orders/{id}로 주문 상태를 업데이트하는 PUT 요청을 추가하고, 인증은 JWT로 처리했는데, 이 과정을 통해 간단한 API라도 구조가 탄탄하면 협업과 유지보수에서 엄청난 차이를 만든다는 걸 형도 느꼈다고 하더라고요.