rest api, 문서만 봐서는 안 잡힙니다 (2026 개념부터 실무까지)

최종 수정일: 2026년 07월 22일

REST API는 정해진 주소(URI)로 요청을 보내면 서버가 데이터를 정해진 형식(주로 JSON)으로 돌려주는, 웹 서비스 간 통신을 위한 설계 원칙입니다. 특정 언어나 프로토콜이 아니라 “이렇게 설계하면 웹의 장점을 잘 살릴 수 있다”는 원칙의 묶음에 가깝습니다. 우리가 스마트폰으로 맛집을 찾고, 메시지를 주고받고, 온라인으로 물건을 사는 이 편리함 뒤에는 REST API가 보이지 않는 곳에서 서비스들을 촘촘하게 연결하며 데이터를 실어 나르고 있습니다.

이 글에서는 REST API의 기본 개념부터 로이 필딩이 정의한 핵심 원칙, 그리고 실제 사용 흐름까지 한 번에 정리합니다. 개념을 “대충 이런 거겠지” 하고 넘기면, 나중에 문서를 읽거나 연동할 때 꼭 한 번씩 막히는 지점이 생깁니다. 처음에 구조를 제대로 잡아두는 것이 결국 가장 빠른 길입니다.

REST API란 무엇인가?

rest api 란

REST API(Representational State Transfer Application Programming Interface)는 현대 웹 서비스의 근간을 이루는 아키텍처 스타일입니다. 여기서 ‘아키텍처 스타일’이란 “이렇게 만들어야만 한다” 같은 기술 규격이 아니라, “이렇게 설계하면 웹의 장점을 잘 살릴 수 있다”는 설계 원칙의 묶음에 가깝습니다.

이 개념은 로이 필딩(Roy Fielding)이 2000년 박사 논문에서 제시했습니다. REST를 처음 접했을 때 인상적이었던 부분도 딱 그 지점이었습니다. 특정 기술에 종속된 프로토콜이 아니라, 유연한 원칙의 집합이라는 점입니다. 개발자에게 자유도를 주면서도, 웹 위에서 일관되고 효율적인 통신 구조를 만들도록 방향을 잡아줍니다.

REST API의 핵심 특징 중 하나는 무상태성(Stateless)입니다. 서버가 클라이언트의 이전 요청 정보를 저장하거나 기억하지 않는다는 뜻입니다. 각 요청은 그 자체로 완전해야 하고, 서버가 처리하는 데 필요한 정보를 모두 담고 있어야 합니다.

예를 들어 쇼핑몰에서 로그인한 뒤 장바구니에 상품을 담는 상황을 떠올려 보시면 됩니다. 무상태 서버는 “방금 로그인했다”는 사실을 기억하지 않습니다. 그래서 장바구니 담기 요청을 보낼 때마다 “내가 누구인지”를 증명하는 값(예: 인증 토큰)을 같이 보내야 합니다.

이 방식이 왜 좋을까요? 서버 구조가 단순해지고, 특정 서버에 문제가 생겨도 다른 서버가 요청을 이어받기 쉬워집니다. 확장성과 안정성이 같이 올라가는 구조입니다.

REST의 또 다른 핵심은 자원(Resource)과 표현(Representation)입니다. REST에서는 시스템의 모든 대상을 고유한 주소, 즉 URI(Uniform Resource Identifier)를 가진 ‘자원’으로 봅니다. 예를 들어 /users/123은 123번 회원이라는 자원의 주소입니다.

클라이언트는 이 주소로 접근하고, HTTP 메서드(GET, POST, PUT, DELETE 등)로 “무슨 일을 할지”를 전달합니다. 집 주소를 보고 찾아가서 초인종을 누르거나(GET), 편지를 넣는(POST) 느낌으로 이해하시면 쉽습니다.

서버는 요청을 받으면 자원의 현재 상태를 특정 형식으로 바꿔 응답합니다. 이 ‘표현’ 형식은 요즘은 JSON이 사실상 표준으로 가장 많이 쓰입니다.

rest api 뜻

‘REST API’라는 용어를 정확히 이해하려면 단어를 쪼개서 보는 게 가장 빠릅니다. REST와 API, 두 개가 합쳐진 말입니다.

제가 외부 서비스 연동 프로젝트를 맡았을 때도 이걸 대충 알고 들어가면 바로 헤매게 되더군요. 예를 들어 슬랙(Slack)으로 자동 알림을 보내는 기능을 만들 때, “자원의 표현을 어떻게 만들고 어떻게 전달할지”를 문서 기준으로 정확히 맞춰야 했습니다.

REST는 Representational State Transfer의 약자이고, 흔히 ‘표현 상태 전이’라고 번역합니다.

• Representational (표현): 자원의 특정 시점 상태를 나타내는 데이터 형태이다
• State (상태): 자원이 가진 데이터 자체이다
• Transfer (전이): 클라이언트와 서버가 표현을 주고받으며 상태가 전달·변경되는 과정이다

API는 Application Programming Interface입니다. 한 소프트웨어가 다른 소프트웨어의 기능이나 데이터를 쓰기 위해 미리 정해둔 약속입니다.

식당으로 비유하면 메뉴판이 API입니다. 손님(클라이언트)은 메뉴판을 보고 주문 가능한 항목과 방식(요청 규칙)을 확인하고, 주방(서버)은 그 주문을 받아 처리합니다. 손님은 주방이 어떻게 요리하는지 몰라도 됩니다. 약속대로 주문하고 결과만 받으면 됩니다.

정리하면 REST API는 API를 REST 원칙에 맞춰 설계한 형태입니다. 원칙을 잘 지킨 API는 RESTful API라고 부르기도 합니다. “REST스럽게 잘 만들었다”는 칭찬에 가깝습니다.

REST API의 원칙

rest api 규칙

RESTful한 API를 설계하려면 로이 필딩이 정의한 6가지 제약 조건을 이해해야 합니다. 이 규칙들이 REST를 REST답게 만드는 핵심입니다. 처음에는 “이걸 다 지켜야 하나?” 싶을 수 있는데, 큰 방향만 잡아도 API 품질이 확 달라집니다.

1. 클라이언트-서버(Client-Server) 구조: 화면과 데이터/로직을 분리한다. 역할이 나뉘면 개발과 유지보수가 쉬워진다
2. 무상태성(Stateless): 서버는 이전 요청을 기억하지 않는다. 요청은 매번 완결되어야 한다
3. 캐시 가능(Cacheable): 응답은 캐시 가능 여부를 명확히 해야 한다. 성능과 비용에 직결된다
4. 일관된 인터페이스(Uniform Interface): 시스템을 단순하게 만드는 핵심 제약이다
5. 계층화 시스템(Layered System): 중간 계층(보안, 캐시 등)이 있어도 클라이언트는 몰라도 된다
6. 코드 온디맨드(Code on Demand, 선택): 필요하면 실행 코드를 내려보낼 수 있다. 다만 보통은 잘 쓰지 않는다

참고로 Uniform Interface는 하위 규칙이 더 있습니다. 여기서부터는 “원칙을 얼마나 빡세게 지키느냐”의 영역으로 들어갑니다.

• 자원의 식별: 자원은 URI로 식별된다
• 표현을 통한 자원 조작: 표현(JSON 등)으로 수정/삭제가 가능해야 한다
• 자기 서술적 메시지: 메시지 자체에 처리 정보가 담겨야 한다
• HATEOAS: 응답에 다음 행동 링크가 포함될 수 있다

API를 처음 설계하신다면, REST 성숙도 모델을 만든 레너드 리처드슨(Leonard Richardson)의 글도 같이 보시는 것을 권합니다. 특히 HATEOAS까지 구현한 Level 3를 “진짜 RESTful”로 보는 관점은, 설계 기준을 잡는 데 도움이 됩니다.

rest api best practices

원칙만 아는 것과, 실제로 “쓰기 좋은 API”를 만드는 것은 또 다릅니다. 실무에서는 모범 사례를 같이 챙겨야 합니다. API는 결국 다른 사람이 쓰는 도구이기 때문입니다.

첫째, 리소스 이름 규칙을 명확히 잡아야 합니다. URI는 직관적이고 예측 가능해야 합니다. 보통 컬렉션은 복수형을 씁니다. 예를 들어 전체 사용자 목록은 /users, 특정 사용자는 /users/123처럼 갑니다. 이 규칙 하나만 지켜도 문서 읽는 시간이 확 줄어듭니다.

둘째, HTTP 메서드를 목적에 맞게 써야 합니다. 의미를 지키면 API 의도가 선명해집니다.

(멱등성(Idempotent)은 여러 번 수행해도 결과가 같은 성질을 말합니다.)

셋째, 응답 데이터 관리가 필요합니다. 한 번에 수만 건을 내려주면 서버와 네트워크가 버티기 어렵습니다. 그래서 페이지네이션을 구현합니다. 보통 limit, offset 같은 파라미터를 씁니다.

필터링, 정렬, 검색도 쿼리 파라미터로 제공하는 경우가 많습니다. 예를 들어 ?status=active&sort=-created_at 같은 형태입니다.

넷째, 보안은 선택이 아닙니다. API 통신은 기본적으로 HTTPS를 사용해야 합니다. 인증은 OAuth 2.0이나 JWT가 많이 쓰입니다. 그리고 요청 제한(Rate Limiting)도 같이 고려해야 합니다.

다섯째, 에러 처리와 문서화는 필수입니다. 실패했을 때 “에러” 한 줄만 주면, 쓰는 사람은 어디서 막혔는지 알 수 없습니다. HTTP 상태 코드와 함께 구체적인 원인을 JSON으로 내려주는 방식이 일반적입니다. 문서화는 OpenAPI(구 Swagger) 같은 표준을 쓰면 관리가 편해집니다.

여섯째, 성능과 버전 관리를 같이 봐야 합니다. 캐싱은 Cache-Control 같은 헤더로 전략을 명시합니다. 버전 관리는 URI(api/v1/)나 헤더 기반으로 미리 설계해 두는 편이 안전합니다. 이걸 뒤로 미루면, 나중에 정말 크게 꼬입니다.

REST API 사용법

how to use rest api

REST API 사용은 결국 “정해진 주소로 HTTP 요청을 보내고, 응답을 받아 처리하는 일”입니다. 단순해 보이지만, 실무에서는 문서를 제대로 읽었느냐가 결과를 갈라놓습니다. 문서 대충 보고 시작하면, 결국 디버깅에 시간을 더 쓰게 됩니다.

기본 흐름은 아래와 같습니다.

1. API 엔드포인트 URL 확인: 문서에서 원하는 기능의 주소를 찾는다
2. 인증 정보 준비: API 키, 토큰 등 요구되는 인증 값을 준비한다
3. HTTP 메서드 선택: 조회는 GET, 생성은 POST 같은 식으로 맞춘다
4. 요청 헤더 및 본문 구성: 토큰, 데이터 형식(Content-Type: application/json) 등을 헤더에 넣고 필요하면 Body를 구성한다
5. 요청 전송 및 응답 수신: 서버로 요청을 보낸다
6. 응답 처리: 상태 코드 확인 후, 성공이면 응답 데이터를 활용한다

테스트 도구로는 cURL이 간단하고 빠릅니다. 요청이 많아지거나 환경 변수를 관리해야 하면 Postman 같은 GUI 도구가 편합니다. 개인적으로는 연동 초기에 Postman으로 한 번씩 다 찍어보고 들어가는 편입니다. 코드로 들어가서 삽질할 확률이 확 줄어듭니다.

언어별로는 Python은 requests, Node.js는 fetch나 axios를 많이 씁니다. 그리고 한 가지는 꼭 말씀드리고 싶습니다. API 키 같은 민감 정보는 소스 코드에 박아두지 말고, 환경 변수로 관리하는 습관을 초반부터 잡아두는 게 좋습니다.

rest api 사용 예제

실제 코드를 통해 REST API를 어떻게 사용하는지 살펴보겠습니다. 가장 널리 알려진 GitHub REST API를 예로 들어보겠습니다.

1. cURL을 사용한 간단한 GET 요청

cURL은 커맨드라인에서 HTTP 요청을 보낼 수 있는 도구입니다. GitHub의 특정 사용자 정보를 조회하는 예제입니다.

이 명령을 실행하면 터미널에 해당 사용자의 이름, 팔로워 수 등이 포함된 JSON 데이터가 출력됩니다.

2. Python requests 라이브러리를 사용한 GET 및 POST 요청

• GET 요청 예제 (사용자 정보 조회)
• POST 요청 예제 (이슈 생성 – 인증 필요)

POST 요청은 데이터를 생성할 때 사용되며, 보통 인증 정보와 전송할 데이터를 함께 보냅니다.

3. JavaScript fetch API를 사용한 GET 요청 (웹 브라우저 환경)

최신 웹 브라우저에는 fetch라는 비동기 HTTP 요청 API가 내장되어 있습니다.

결국 핵심은 3가지입니다. 엔드포인트를 정확히 찾고, 메서드를 맞추고, 인증과 데이터를 빠짐없이 담는 것입니다.

jira rest api

Jira는 Atlassian에서 만든 프로젝트 관리 및 이슈 추적 도구입니다. Jira REST API는 Jira 기능을 프로그래밍 방식으로 제어하고 자동화할 수 있게 해주는 인터페이스입니다. 다른 시스템과 통합하거나 반복 작업을 자동화할 때 특히 많이 씁니다.

Jira는 배포 환경(Jira Cloud, Jira Server 등)에 따라 API 버전이나 주소 형식이 조금씩 다를 수 있습니다. 그래서 사용 전에는 공식 문서를 먼저 확인하셔야 합니다. 인증은 개인용 액세스 토큰(PAT)이나 API 토큰 기반 방식이 많이 권장됩니다.

Jira REST API로 다룰 수 있는 주요 자원은 아래와 같습니다.

• 이슈(Issue): 생성, 조회, 수정, 삭제, 상태 변경이 가능하다
• 프로젝트(Project): 작업이 묶이는 공간이다
• 사용자(User): 사용자 정보를 관리한다
• 댓글(Comment): 이슈 댓글을 추가하거나 조회한다

Jira REST API에서 많이들 좋아하는 기능이 JQL(Jira Query Language)입니다. SQL처럼 조건을 조합해서 이슈를 정교하게 검색할 수 있습니다. JQL을 잘 쓰면 “원하는 데이터만 정확히 뽑는 자동화”가 가능해집니다.

다음은 Python의 requests 라이브러리를 사용해 Jira Cloud에 새 이슈를 생성하는 코드 예제입니다.

이처럼 Jira REST API는 단순 조회를 넘어, 운영과 개발 업무를 자동화하는 데 꽤 강력한 도구입니다.

여기까지 REST API를 정리해 봤습니다. REST는 특정 기술이 아니라 웹의 장점을 살리기 위한 설계 원칙이고, 원칙을 이해한 뒤 모범 사례까지 챙기면 확장성과 유지보수성이 좋은 서비스를 만들기 훨씬 수월해집니다.

FAQ

Q1: REST와 SOAP의 가장 큰 차이점은 무엇입니까?

A: REST는 아키텍처 스타일(가이드라인)이고 SOAP은 표준 프로토콜이라는 점입니다. REST는 HTTP를 그대로 활용하면서 JSON, XML 등 다양한 형식을 유연하게 쓸 수 있습니다. 반면 SOAP은 XML 기반의 정해진 메시지 구조를 따라야 하고, HTTP 외 프로토콜에서도 동작할 수 있어 구조가 더 무겁고 복잡해지는 편입니다.

Q2: ‘무상태성(Stateless)’이 REST API에서 왜 중요합니까?

A: 서버가 클라이언트 상태를 저장하지 않기 때문에 설계가 단순해지고, 어떤 서버가 요청을 처리해도 동일한 처리가 가능해집니다. 부하 분산에 유리하고, 특정 서버 장애가 나도 다른 서버가 요청을 이어받기 쉬워 서비스 안정성이 올라갑니다.

Q3: HATEOAS란 무엇이며, 왜 REST 성숙도의 가장 높은 단계로 보기도 합니까?

A: HATEOAS(Hypermedia as the Engine of Application State)는 응답에 “다음에 할 수 있는 행동” 링크를 포함시키는 원칙입니다. 예를 들어 주문 조회 응답에 주문 취소나 배송 조회 링크를 같이 주는 방식입니다. 클라이언트는 링크를 따라가면 되니, 엔드포인트가 바뀌어도 수정 범위가 줄어들 수 있습니다. 클라이언트와 서버 결합도를 낮춘다는 점에서 높은 단계로 평가됩니다.

Q4: REST API 설계에서 URI에 복수형 명사(예: /users)를 권장하는 이유는 무엇입니까?

A: 직관성과 일관성을 높이기 위해서입니다. /users는 컬렉션(집합), /users/123은 특정 요소를 의미하는 구조가 명확해집니다. 단수형을 쓰면 관계가 애매해질 수 있습니다.

Q5: REST API 테스트에 자주 쓰는 도구는 무엇입니까?

A: 크게 두 가지입니다. 커맨드라인 기반은 cURL이 대표적이고, GUI 기반은 Postman, Insomnia 등이 많이 쓰입니다. GUI 도구는 환경 변수, 요청 기록, 컬렉션 관리 같은 기능이 있어 테스트가 커질수록 편해집니다.