Rest API

제가 처음 개발하면서 “와 이거 진짜 마법인데?” 싶었던 순간이 있어요. 서로 다른 서비스가 사람처럼 대화하듯 정보를 주고받는 걸 처음 봤을 때였거든요. 날씨 앱은 어떻게 실시간 구름 사진을 뿌려주는지, 쇼핑몰에서 결제 버튼 누르면 카드사랑 은행이 어떻게 그 짧은 순간에 처리를 끝내는지, 이런 거 한 번쯤 궁금했죠.

그 중심에 보통 REST API가 있습니다. 이 글은 용어만 줄줄 외우는 느낌 말고요, 제가 삽질하면서 “아 그래서 이렇게 하는 거구나” 하고 감 잡았던 포인트들 위주로, REST API가 뭐고 왜 다들 이걸 기본값처럼 쓰는지 편하게 풀어볼게요.

REST API 기본 개념

처음엔 단어가 좀 낯설 수 있는데요, 막상 뜯어보면 웹이 원래 하던 방식을 “그럴듯하게 규칙으로 정리한 것”에 가깝습니다. REST는 완전히 새로운 기술이라기보단, 웹을 웹답게 쓰기 위한 설계 철학, 모범 사례 같은 느낌이에요.

저도 처음엔 이게 뭐가 이렇게 거창하나 싶었는데, 한 번 정리되고 나니까 웹 통신이 머릿속에서 좀 정돈되더라고요.

REST API의 뜻은 무엇인가요?

REST API는 ‘Representational State Transfer Application Programming Interface’의 줄임말입니다. 2000년에 로이 필딩(Roy Fielding)이 박사 논문에서 처음 소개했어요. “웹을 가장 웹답게, 효율적으로 쓰려면 어떻게 해야 하지?” 같은 고민 끝에 REST라는 아키텍처 스타일을 제안한 거죠.

그가 말한 핵심은 이런 쪽입니다.
> “REST는 웹의 기존 기술과 HTTP 프로토콜을 그대로 활용하기 때문에 웹의 장점을 최대한 활용할 수 있는 아키텍처 스타일”

그러니까 뭔가를 새로 발명했다기보단, 이미 잘 굴러가던 웹 표준을 일관되게 쓰는 방법을 정리해 둔 거라고 보면 편합니다.

비유 하나 들어볼게요. 식당에서 손님(클라이언트)이 메뉴판(서버가 제공하는 자원 목록)을 보고 김치찌개(자원, Resource)를 주문하죠. 그러면 주방(서버)이 김치찌개를 만들어서 테이블로 가져다줍니다. 이때 손님이 받는 건 “먹을 수 있는 형태”잖아요. REST에서 말하는 표현(Representation)이 딱 그 느낌이에요.

웹에 있는 데이터나 기능을 REST에서는 자원(Resource)이라고 부르고, 자원은 /users/123 같은 고유한 주소(URI)를 가집니다. 클라이언트가 그 주소로 요청하면 서버가 자원의 현재 상태를 표현해서 내려주고요. 보통 JSON이나 XML 같은 형식으로 주고받습니다.

그리고 조회하고, 만들고, 수정하고, 삭제하는 것처럼 자원의 상태를 바꾸는 행위를 상태 전달(State Transfer)이라고 부르는데요, 이게 HTTP 메서드로 이뤄집니다.

다음 표는 HTTP 메서드가 보통 어떤 역할을 하는지 정리한 거예요.

생각보다 복잡한 규약이라기보단, 웹의 기본 원리를 꽤 직관적으로 정리한 방식이라고 보면 됩니다.

REST API란 무엇인가요?

REST가 설계 철학이라면, REST API는 그 철학을 따라 실제로 만든 “시스템 간 소통 창구”라고 보면 돼요. REST라는 설계도를 보고 지은 건물 같은 거죠.

MDN 같은 문서에서는 보통 이렇게 정리하더라고요.
> “HTTP 요청을 통해 소통하며, 주로 JSON 형태로 데이터를 주고받는 웹 API”

제가 이 정의를 좋아하는 이유는, 웹 표준(HTTP)을 기반으로 하니까 언어나 플랫폼에 덜 묶인다는 점이 같이 따라오거든요. 자바든 파이썬이든, 모바일이든 서버든, 결국 HTTP로 얘기하면 됩니다.

그리고 REST API에서 자주 나오는 얘기가 HTTP 메서드를 “원래 의미대로” 쓰자는 거예요. 예를 들어 GET은 조회만 해야지, 서버 데이터를 바꾸면 안 됩니다. 이걸 안전성(Safety)이라고 부릅니다.

PUT이나 DELETE는 멱등성(Idempotency)을 가져야 하고요. 멱등성은 말이 어려운데, 엘리베이터 버튼 생각하면 편해요. 한 번 누르든 여러 번 누르든 결과가 같죠. 같은 요청을 여러 번 보내도 서버 상태가 한 번 보낸 것과 같게 유지되는 성질입니다.

이거 실무에서 은근히 중요해요. 네트워크가 불안해서 같은 요청이 재시도되는 상황이 꽤 자주 나오거든요. 멱등성이 잘 지켜져 있으면 “아 또 두 번 들어가서 데이터 꼬였네…” 같은 삽질을 많이 줄일 수 있습니다.

REST API의 핵심 규칙은 무엇인가요?

RESTful한 API가 되려면 로이 필딩이 말한 6가지 제약 조건을 따라야 합니다. 이걸 다 100% 지키는 게 현실에서 늘 쉬운 건 아닌데요, 방향성으로는 꽤 도움이 됩니다.

1. 클라이언트-서버 분리 (Client-Server Separation): 화면(클라이언트)과 데이터 처리(서버)를 역할로 분리합니다. 앱 UI를 갈아엎어도 서버는 그대로 둘 수 있고, DB를 바꿔도 사용자는 잘 모르게 만들 수 있어요.
2. 무상태성 (Stateless): 서버가 클라이언트의 이전 상태를 기억하지 않는다는 원칙입니다. 서버가 기억을 안 하니까, 요청 하나가 그 자체로 완결된 정보를 담고 있어야 해요. 덕분에 서버를 수평 확장하기가 훨씬 편해집니다.
3. 캐시 가능성 (Cacheable): 응답이 캐시 가능한지 명확히 해서, 자주 쓰는 데이터는 재사용할 수 있게 합니다. 속도도 좋아지고 서버 부담도 줄어요.
4. 계층화된 시스템 (Layered System): 클라이언트와 서버 사이에 로드밸런서, 게이트웨이, 보안 장비 같은 중간 계층을 둘 수 있습니다. 예전에 금융 쪽 프로젝트 할 때, 인증 계층을 끼워 넣는 작업을 큰 충격 없이 했던 기억이 나네요.
5. 통일된 인터페이스 (Uniform Interface): REST의 핵심입니다. 다들 같은 규칙으로 소통하게 만드는 거예요.

자원의 식별 모든 자원은 /users/123 같은 URI로 식별돼야 합니다.
표현을 통한 자원 조작 클라이언트는 JSON 같은 표현을 주고받으면서 상태를 바꿀 수 있어야 합니다.
자기 서술적 메시지 예를 들어 Content-Type: application/jsonCopy처럼 “이게 뭔 데이터인지” 메시지 자체가 설명해줘야 합니다.
HATEOAS 응답에 다음 행동 링크를 포함해서, 클라이언트가 그걸 보고 다음 액션을 이어갈 수 있게 하는 개념입니다.

1. 주문형 코드 (Code on Demand, 선택): 필요하면 서버가 실행 가능한 코드(예: JavaScript)를 내려서 클라이언트 기능을 확장할 수 있다는 규칙인데, 이건 선택 사항입니다.

이 규칙들을 잘 지켜서 API를 만들면, 문서가 조금 덜 친절해도 “대충 이렇게 쓰면 되겠네” 하고 감이 오는 API가 됩니다. 협업할 때 특히 차이가 나요.

REST API 활용 사례

개념만 보면 좀 뜬구름 같을 수 있는데요, 실제로는 우리가 쓰는 서비스 대부분이 REST API로 서로 붙어 있습니다. 저도 실무에서 “아 이래서 다들 REST REST 하는구나”를 체감한 게 결국 이런 연결 작업들이었어요.

REST API 사용 예제

REST API의 기본 활용은 CRUD를 HTTP 메서드에 매핑하는 겁니다. 독서 기록 앱을 만든다고 상상해볼게요.

내 서재의 모든 책 조회하기 (Read)
요청 GET /api/books
설명 내가 등록한 모든 책 목록을 요청합니다.
응답 200 OK 와 함께
[{"id": 1, "title": "어린 왕자"}, {"id": 2, "title": "데미안"}]Copy
같은 JSON을 받습니다.

새로운 책 추가하기 (Create)
요청 POST /api/books
요청 내용 {"title": "사피엔스", "author": "유발 하라리"}Copy
설명 새 책 정보를 서버에 보내 등록을 요청합니다.
응답 201 Created 와 함께
Location: /api/books/3Copy 같은 새 자원 주소를 돌려받습니다.

특정 책의 상세 정보 보기 (Read)
요청 GET /api/books/1Copy
설명 1번 책 상세 정보를 요청합니다.
응답 200 OK 와 함께
{"id": 1, "title": "어린 왕자", "author": "생텍쥐페리"}Copy
같은 데이터를 받습니다.

책 정보 수정하기 (Update)
요청 PUT /api/books/1Copy
요청 내용 {"title": "어린 왕자(리커버 에디션)", "author": "생텍쥐페리"}Copy
설명 1번 책 정보를 새 내용으로 덮어씁니다.
응답 200 OK 와 함께 수정된 정보를 받습니다.

책 삭제하기 (Delete)
요청 DELETE /api/books/1Copy
설명 1번 책을 삭제합니다.
응답 204 No Content 로 “삭제는 됐고, 보여줄 본문은 없음”을 알려줍니다.

제가 2022년 가을에 사내 도서 관리 시스템 프로젝트를 했을 때도 거의 이 패턴이었어요. POST /books로 새 책을 등록하고, GET /books?query=...Copy로 검색 붙이고요. 규칙이 명확하니까 프론트 개발자랑 “이건 이렇게 부르면 돼요” 하고 합 맞추는 시간이 확 줄더라고요.

Jira REST API

Jira는 개발팀에서 프로젝트 관리랑 이슈 트래킹할 때 진짜 많이 쓰죠. Jira REST API를 쓰면, 웹에서 클릭으로 하던 작업들을 스크립트로 자동화할 수 있습니다. 버그 티켓 만들기, 상태 변경, 댓글 달기 같은 것들이요.

저희 팀은 빌드가 실패하면 CI/CD에서 Jira API를 호출해서 버그 티켓이 자동으로 생성되게 해뒀어요. 반대로 PR 머지하고 커밋 메시지에 이슈 번호가 있으면, 그걸 읽어서 상태를 자동으로 ‘완료’로 바꾸는 것도 돌리고 있고요. 이런 거 한 번 맛보면, 반복 작업으로 시간 새는 게 확 줄어서 체감이 큽니다.

GitHub REST API

GitHub은 협업의 중심지죠. GitHub REST API로 리포지토리 만들기, 이슈 관리, Pull Request 처리 같은 걸 외부에서 제어할 수 있습니다.

저는 PR이 열리면 코드 스타일 검사 돌리고, 문제 있으면 댓글로 남기는 자동화를 꽤 유용하게 쓰고 있어요. 사람이 매번 “여기 공백” “여기 린트” 이런 얘기만 하다 끝나면 서로 피곤하잖아요. 그런 잔소리를 기계가 먼저 해주면, 리뷰는 로직이랑 구조 얘기에 집중할 수 있어서 훨씬 낫더라고요.

Confluence REST API

Confluence는 팀 문서 창고로 많이 씁니다. 회의록, 기획서, 기술 문서 같은 것들이 쌓이죠. Confluence REST API는 이런 문서를 프로그래밍으로 만들거나 수정하고, 다른 시스템이랑 연결하는 데 좋아요.

예전엔 배포 끝날 때마다 막내가 Jira 티켓 뒤져가며 릴리스 노트를 손으로 정리하곤 했는데요. Confluence API 붙이고 나서는 버튼 한 번으로 자동 생성되게 바뀌었습니다. Jira에서 티켓 뽑아오고, Confluence에 정해진 템플릿으로 페이지 만들어 올리는 식이요. 이런 자동화는 한 번 해두면 팀 전체가 편해집니다.

Tableau REST API

Tableau는 BI 도구고, REST API는 대시보드 자체를 막 조작한다기보단 사용자 추가, 권한 설정, 게시 같은 운영 작업 자동화에 많이 씁니다.

신규 입사자나 부서 이동이 잦은 조직에서는 권한 관리가 진짜 노가다예요. 제가 있던 회사는 인사 시스템이랑 Tableau API를 연동해서, 입사 등록되면 부서에 맞는 그룹에 자동으로 넣어주게 했습니다. 운영 부담이 확 줄고, 권한 누락 같은 사고도 줄어서 꽤 만족도가 높았어요.

각 서비스별 활용 사례는 표로 한 번 더 정리해둘게요.

FAQ