REST API vs RESTful API

📅 날짜: 2026년 4월 11일

REST에 대해

💡REST 란?

웹의 장점을 최대한 활용하기 위해 만들어진 아키텍처 스타일이다.

복잡하게 들릴 수 있지만, 핵심은 자원(Data)을 어떻게 이름 붙이고(URL), 어떻게 처리할지(HTTP Method)에 대한 약속이다.

REST의 핵심 개념

구분	내용	비유
자원(Resource)	우리가 얻고자 하는 데이터(예 : 사용자 정보, 게시물, 상품, 장바구니, 결제 수단 등)	메뉴판에 있는 음식
행위(Verb)	데이터에 대해 무엇을 할 것인가(HTTP 메서드 사용)	주문 방식 (주문하기, 취소하기 등)
표현 (Representation)	데이터를 어떤 형식으로 보여줄 것인가(JSON, XML 등)	음식이 담겨 나오는 그릇

• 자원 : 쇼핑 자원 → 상품, 장바구니, 결제 수단
  • URL → /items, /carts. /payments → A서버주소/items ⇒ A서버가 관리하는 상품(items)에 URL로 접근!!
• 행위 : HTTP 메서드
  • GET : 조회(Read)
  • POST : 생성(Create)
  • PUT/PATCH : 수정(Update)
  • DELETE : 삭제(Delete)
• 표현 : JSON 형식 ? OR XML형식 ? → 어떤 형식을 사용할거냐?

REST 설계원칙 6가지

• 균일한 인터페이스(Uniforn Interface)
  • URL, HTTP 등의 표준화된 방법을 사용한다.
  • HTTP 표준만 따른다면 어떤 언어나 플랫폼에서도 사용할 수 있는 공통된 인터페이스를 가져야 한다.
• 무상태(Stateless)
  • 서버는 클라이언트의 상태를 저장하지 않는다. 각 요청은 독립적이며 필요한 모든 정보를 포함해야 한다.
• 클라이언트 - 서버 분리(Client-Server Architecture)
  • 클라이언트가 UI를 처리한다.
  • 서버는 데이터 저장, 보안, 워크로드를 담당한다.
  • 클라이언트와 서버는 명확히 구분되어야 한다.
• 계층화 시스템(Layered System)
  • 클라이언트는 서버와 직접 통신하지 않고 중간 계층을 거친다.
  • 통신 대상이 최종 서버인지 중개자(보안, 로드 밸런싱 등)인지 알 수 없도록 설계해야 한다.
  • 서버는 요청을 다른 서버로 전달할 수 있다.
• 캐시 가능성(Caching)
  • 응답은 캐싱이 가능해야 한다.
  • HTTP의 기존 캐싱 기능을 사용하여 서버의 부하를 줄이고 성능을 향상시킬 수 있다.
  • 예) 모든 페이지에 공통 머리글 및 이미지가 있는 웹 사이트를 방문한다고 했을 때 새로운 웹 사이트 페이지를 방문할 때마다 서버는 동일한 이미지를 다시 전송해야 한다. 이를 피하기 위해 클라이언트는 첫 번째 응답 후에 해당 이미지를 캐싱하거나 저장한 다음 캐시에서 직접 이미지를 사용한다.
• 온디맨드 코드(Code on Demand)
  • 서버가 클라이언트에서 실행 가능한 코드를 전송할 수 있다.
  • 예) 웹 사이트에서 등록 양식을 작성하면 브라우저는 잘못된 전화번호와 같은 실수를 즉시 강조 표시한다. → 서버에서 전송한 코드로 인해 이 작업을 수행할 수 있다.

---

API에 대해

💡API 란?

서로 다른 소프트웨어 애플리케이션이 서로 통신하고 데이터를 주고 받을 수 있게 해주는 매개체이자 규칙의 집합이다.

핵심 역할

• 통로 역할 : 프로그램 간의 데이터 전송 통로를 제공한다.
• 표준화 : 서로 다른 언어로 만들어진 프로그램이라도 API라는 공통 규격이 있다면 대화가 가능하다.
• 보안 : 내부 소스 코드를 공개하지 않고도 필요한 기능만 외부에 노출하여 사용할 수 있게 한다.

배달 앱의 배달비 계산기 예시

• 입력 데이터(Request) : 사용자의 집 주소와 주문 금액을 API에 전달
• API의 역할
  1. 주소를 확인해 식당과의 거리를 계산
  2. 현재 날씨(비가 오는지 등)와 배달원의 수급 상황을 체크
  3. 주문 금액에 따른 할인 혜택을 적용
• 결과 반환(Response) : 최종적으로 사용자에게는 배달비 3000원이라는 결과만 딱 보여준다.
• 주소 예시 : POST /calculate_delivery_fee
  • calculate(계산하다)라는 동사

도서관의 도서 검색 키오스크 예시 (RESTful)

• 요청(Request) : 키오스크 화면에 짱구라는 책 제목을 입력
• 내부 처리 : 시스템은 도서관의 수만 권의 책 DB에서 “짱구”를 찾고, 현재 대출 중인지, 어느 서가에 있는지 확인
• 응답(Response) : 대출 가능/3층 만화책 코너/청구기호 811.4라는 정보를 화면에 띄운다.
• 주소 예시 :GET /books/123
  • books(책)라는 명사

💡인터페이스란?

• 둘 이상이 마주 보고 소통하는 접점이라는 뜻으로 연결에 의미를 가진다.
• 예) TV리모컨은 사람과 TV 프로그램이 소통하는 인터페이스

REST 응답에 대해

💡REST 응답 이해하기

• 상태 코드(state code) : 결과를 설명한다. (예 : 200, 201, 204, 400, 401, 404, 500)

• 헤더 (header) : 메타데이터 (예 : 콘텐츠-타입, 캐시-제어, 속도 제한 헤더)

• 본문 (body) : 데이터 표현 (JSON)

  HTTP/1.1 200 OK
  Content-Type: application/json
  Cache-Control: max-age=3600
  X-RateLimit-Remaining: 95
  {
    "success": true,
    "data": {
      "product_id": "789",
      "name": "Developer Toolkit",
      "price": 49.99
    }
  }"

REST API에 대해

💡REST API 란?

위의 REST원칙을 기반으로 한 API 설계 방식이다.

• 웹 자원을 URL로 정의하고, HTTP 메서드를 이용해 해당 자원에 대한 CRUD 작업을 수행한다.

  HTTP 메서드	URL	설명
  GET	/users	모든 유저 정보를 불러온다.
  GET	/users/1	특정 유저(pk=1) 정보를 불러온다.
  POST	/users	새로운 유저를 생성한다.
  PUT	/users/1	특정 유저(pk=1) 정보를 전체 수정한다.
  PATCH	/users/1	특정 유저(pk=1) 정보를 부분 수정한다.
  DELETE	/users/1	특정 유저(pk=1) 정보를 삭제한다.

1. 안정성(Safe)
   • GET 메서드(조회)는 안전하다.
     • 저장된 데이터를 반환하지 않는다.
   • POST, DELETE, PUT, PATCH는 안전하지 않다.
     • 데이터를 생성, 수정, 삭제한다.
2. 멱등성(Idempotent)
   • 한번을 호출하거나 수천번을 호출하거나 항상 결과는 같다.
     • GET → 같은 결과가 계속 조회된다.
     • PUT → 수정해서 대체된 후의 결과는 계속 같다.
     • DELETE → 같은 요청을 여러번해도 삭제된 결과는 같다.
     • POST → 멱등성을 보장하지 않는다.
       • 누를 때마다 데이터가 계속 새로 생김
   
3. 캐시 가능성(Cacheable)
   • 재사용을 위해 요청에 대한 응답을 저장할 수 있을까?
     • GET, HEAD, POST 메소드는 캐시가 가능하다.
     • 일반적으로 GET, HEAD 정도만 캐시로 사용한다.
     • 변경 가능성이 적은 정적 자원(HTML, CSS, IMAGE, JS 등)을 주로 캐싱한다.

REST API의 URL 네이밍 규칙

1. 명사를 사용하여 리소스를 표현

   • 리소스는 동사가 아닌 명사로 표현
   • 단일 리소스(객체 인스턴스 등)에 대해서는 단수 명사를 사용
   • 클라이언트 및 서버 리소스에 대해서는 복수 명사를 사용

   ✅ 올바른 예시
   GET /users
   GET /users/admin
   GET /users/{id}/playlists
   
   ❌ 잘못된 예시
   GET /getUsers
   GET /users/admins
   GET /user/{id}/playlist

2. 일관성이 핵심

   • 계층적 관계를 나타내기 위해서는 슬래시( / )를 사용
   • URL 마지막에 슬래스( / )를 사용하지 않는다.
   • URL 가독성을 위해 하이픈( - )을 사용
   • 언더라인( _ )을 사용하지 않는다.
   • URL에 소문자를 사용

   ✅ 올바른 예시
   GET /order-management/customer-orders
   GET /order-management/customer-orders/{order-id}
   GET /order-management/customer-orders/{order-id}/order-items
   
   ❌ 잘못된 예시
   GET /order-management/customer-orders/
   GET /ordeManagement/customerOrders
   GET /order_management/customer_orders

3. 파일 확장자를 사용하지 않는다.

   • URL에 파일 확장자를 사용하지 않는다.

   ✅ 올바른 예시
   GET /content-management/authors
   
   ❌ 잘못된 예시
   GET /content-management/authors.xml

4. CRUD 함수 이름을 사용하지 않는다.

   • URL에 CRUD 기능을 나타내는 단어를 사용하지 않는다.

   ✅ 올바른 예시
   GET /user-accounts
   
   ❌ 잘못된 예시
   GET /get-all-users

5. 쿼리 파라미터를 사용해 리소스를 필터링한다.

   • 새로운 API 생성을 지양하고, 쿼리 파라미터를 사용해 리소스를 필터링한다.

   ✅ 올바른 예시
   GET /drivers?status=active
   GET /drivers?region=KR&age=30
   GET /drivers?page=2&limit=100

REST API의 작동원리에 대해

💡REST API의 작동 원리

1. 클라이언트가 요청을 시작한다.

   • 애플리케이션이 API 앤드포인트에 HTTP 요청을 보낸다.

2. 네트워크 이동 요청

   • 네트워크 이동 요청 : 요청은 HTTP/HTTPS를 통해 인터넷을 통해 서버에 도달한다.

3. 서버가 요청을 처리

   • API는 입력을 검증하고 논리나 기능을 수행

4. DB 운영

   • 필요 시 서버가 DB를 조회하거나 업데이트 한다.

5. 응답 생성

   • 서버는 상태 코드, 헤더, 본문이 포함된 구조화된 응답(종종 JSON 형식)을 반환

6. 답변이 돌아옴

   • 클라이언트는 응답을 받고 UI 렌더링, 로그, 추가 호출 등 이를 처리
   

---

RESTful API에 대해

💡REST 설계 원칙을 충실하게 제대로 지키는 API를 의미

• URL + HTTP Method만 보고도 무슨 API인지 식별할 수 있어야 한다.
  • 예 ) www.쇼핑몰.com/categories/2/products/1 + GET, PUT, PATCH, DELETE

구분	REST(배달 앱 방식)	RESTful(도서관 방식)
설계 초점	어떤 기능을 수행할 것인가?	어떤 자원을 다룰 것인가?
URL 구조	/get_price, /order_food(동사 포함 가능)	/prices, /orders(오직 명사만 사용)
가독성	개발자가 정한 규칙을 따로 공부해야 함	주소와 메서드만 봐도 누구나 의도를 이해함
엄격함	“데이터만 잘 오가면 되지!!” (실용주의)	“원칙을 지켜야 유지보수가 쉽다” (원칙 주의)

• 비-RESTful: /get_work_hours?name=홍길동&start=20240101 (동사 사용)
• RESTful: GET /employees/hong-gildong/work-hours?from=2024-01-01&to=2024-01-31 (자원 중심)

📌
Q. 이 API는 REST API인가요?
A. 그건 REST API라고 부를 순 있지만, 원칙을 어겼으니 RESTful 하지는 않네요.
→ 좀 더 전문가 느낌

RESTful API 요청 처리 흐름(5단계)

RESTful API 요청 처리 흐름 (5단계)

1. [출입구] Controller : 클라이언트의 요청을 가장 먼저 받는다. 요청 주소(URL)와 방식(GET, POST 등)을 확인하고 담당자(Service)에게 넘긴다.
   1. 클라이언트 : “규격에 맞춰서 보낼게 GET방식으로 /users/1주소로 요청!!”
   2. 컨트롤러 : “오케이, 1번 유저 정보 달라는 거지? Service야! 데이터 좀 가져와 봐”
2. [개념 ] Stateless (무상태성) : 이 시점에서 클라이언트가 보낸 인증 정보(token 등)를 확인한다.
   1. “서버는 당신이 누군지 기억하지 않는다. 그러니 요청서에 모든 정보를 다 담아서 왔겠지?”
3. [인증/검증] Security/Filter (필터) : (선택 사항 / 중요) 요청한 사람이 맞는지, 권한이 있는지 확인한다.
4. [주방] Service (서비스) : 실제 핵심 로직 (계산, 가공 등)을 처리한다. 데이터가 필요하면 창고(Repository)에 요청한다.
   1. DB가기 전 : “잠깐만, Repository야 DB가서 1번 유저 있는지 확인해봐!”
   2. DB간 후 : “받았다! 이 데이터를 클라이언트가 보기 좋게 가공해서 Controller에게 줄게!”
5. [창고] Repository(레포지토리) : DB에 직접 접근하여 데이터를 가져오거나 저장한다.
   1. “여기 있어!(DB에서 데이터를 꺼내 Service에 전달)”
6. [반환] Controller : 서비스가 처리한 결과를 받아서, 클라이언트에게 규격(JSON + 상태 코드)에 맞춰 응답을 보낸다.
   1. “완벽해! 상태 코드 200 ok 찍고, 결과물은 JSON으로 포장해서 클라이언트에게 보낸다.”

• RESTful API 배달 시스템으로 예시
  • 클라이언트 (손님): 앱으로 GET /pizzas/1 (1번 피자 주세요)라고 규격화된 주문을 넣는다.
  • Controller (카운터 직원): 주문을 접수하고, 주방(Service)에 전달합니다. 마지막에 완성된 피자를 손님에게 배달한다.
  • Service (요리사): 피자를 만듭니다. 재료가 필요하면 창고(Repository)에서 가져온다.
  • Repository (창고 관리자): 냉장고(DB)에서 재료를 꺼내 요리사에게 준다.
  • 응답 (배달): 카운터 직원이 피자와 함께 200 OK (성공) 영수증을 붙여 손님에게 보낸다.
    

RESTful API 서버 응답에 무엇이 포함되어있을까?

1. 상태 표시줄

• 2xx : 일반 성공 응답
• 201 : POST 메서드 성공 응답
• 4xx : 서버가 처리할 수 없는 잘못된 요청(클라이언트 잘못)
• 404 : 리소스를 찾을 수 없음
• 5xx : 서버 내부 오류

2. 메시지 본문

• 응답 본문에는 리소스 표현이 포함된다.
• 클라이언트는 데이터 작성 방식을 XML 또는 JSON 형식으로 정보를 요청할 수 있다.
• 예 ) 클라이언트가 John이라는 사람의 이름과 나이를 요청하면 서버는 JSON 형식으로 반환한다.

'{"name":"John", "age":30}'

3. 헤더

• 응답에는 응답에 대한 헤더 또는 메타이터도 포함된다.

• Content-Type (중요!!)

  • 서버가 보내는 본문 데이터가 어떤 형식인 알려준다.
  • application/json : 가장 많이 쓰이는 JSON 형식
  • text/html : HTML 페이지
  • image/png : 이미지 파일

  → 이 헤더가 있어야 클라이언트(브라우저)가 데이터를 글자로 보여줄지, 그림으로 보여줄지 결정한다.
  

• Cache-Control

  • 데이터를 브라우저에 얼마나 오래 저장(캐싱)해둘지 결정한다.
  • no-store : 절대 저장하지 마라(보안이 중요한 데이터)
  • max-age=3600 : 1시간 동안은 서버에 다시 묻지 말고 저장된 걸 써라

  → 이를 통해 서버 부하를 줄이고 속도를 높일 수 있다.
  

• Set-Cookie

  • 서버가 클라이언트에게 “이 정보를 네 컴퓨터에 저장해둬”라고 요청할 때 사용한다.
  • 주로 로그인 세션 정보나 사용자 설정 값을 저장하여 다음 요청 때 클라이언트가 다시 보낼 수 있게 한다.
  • 만료기간(expire, max-age), 사용될 위치(domain, path)를 설정할 수 있다.
  • 주의할 점
    • 항상 서버에 전달되니 최소한의 정보만 사용하여 트래픽을 최적화 시켜야 한다.
    • 탈취 당하기 쉬우니 보안에 민감한 개인정보 등은 저장하지 않는다.

• Access-Control-Allow-Origin(CORS 관련)

  • 이 응답은 어떤 웹사이트에서 읽을 수 있는지 허용 범위를 나타낸다.
  • 보안상의 이유로 브라우저는 다른 도메인에서의 API 호출을 막는데, 이를 허용해줄 때 사용하는 아주 중요한 헤더이다.

• Location

  • 새로운 리소스가 생성되었거나(201 Created), 페이지가 이동했을 때 (3XX) 이동할 URL 주소를 담는다.

RESTful API 인증 방법에 대해

💡RESTful API 인증

인증은 당신이 누구인지 증명하는 과정이다. 서버는 신뢰할 수 있는 요청인지 확인한 뒤에만 리소스를 제공한다.

1. HTTP 기본 인증 (Basic Auth)
   • 방식 : Authorization : Basice [ID:PW를 Base64로 인코딩한 값
   • 주의 : Base64는 암호화가 아닌 단순 인코딩이므로, 반드시 HTTPS 암호화 통신과 함께 사용해야 한다.
2. 전달자 인증(Bearer/Token Auth)
   • 방식 : Authorization: Bearer [Access_Token]
   • 장점: 서버가 상태를 저장하지 않는(Stateless) REST의 특성에 가장 잘 맞다. 토큰에 유효 기간을 설정할 수 있어 보안성이 높다.
3. API 키 (API Key)
   • 방식: 쿼리 파라미터나 헤더(x-api-key)에 키를 포함한다.
   • 용도: 서비스 이용 권한 확인 및 트래픽 제한(Throttling) 관리에 주로 쓰인다.
4. OAuth 2.0 (Open Authorization)
   • 핵심: 사용자가 서비스(A)에 자신의 비밀번호를 주지 않고도, 다른 서비스(B)의 자원을 쓸 수 있게 해주는 권한 위임 표준이다.
   • 구성: Access Token, Refresh Token을 사용하여 매우 세밀한 보안 제어가 가능하다.
5. WWW-Authenticate
   • 방식 : 이 헤더는 주로 401 Unauthorized 상태 코드와 함께 세트로 움직인다.
   • 상황: 클라이언트가 인증 정보 없이(혹은 잘못된 정보로) 보호된 리소스에 접근한다.
   • 서버의 응답: "안돼! (401)"라고 하면서 WWW-Authenticate 헤더에 어떤 인증 방식을 써야 하는지 적어서 보낸다.
   • WWW-Authenticate: Basic realm="api" (ID/PW 방식 요구)
   • WWW-Authenticate: Bearer realm="token_required" (토큰 방식 요구)

---

🔗 참고 자료 (Reference)

스파르타 웹 개발 기초 강의 자료

https://devpro.kr/posts/rest-restful-api/

https://blog.postman.com/rest-api-examples/
https://aws.amazon.com/ko/what-is/restful-api/