REST API란 무엇인가? 기초부터 실전까지

REST API란 무엇인가? 기초부터 실전까지

이 글은 소프트웨어 개발에 입문한 초보자를 대상으로 REST API의 개념, 원리, 설계 방법, 실전 예시까지 상세히 설명합니다. REST API가 무엇인지, 왜 중요한지, 그리고 실제로 어떻게 사용하는지 차근차근 이해할 수 있습니다.

1. API란 무엇인가?

API의 기본 개념

API(Application Programming Interface)는 소프트웨어끼리 서로 정보를 주고받을 수 있도록 정해둔 약속, 즉 “인터페이스”입니다. 예를 들어, 여러분이 스마트폰의 날씨 앱을 실행했을 때, 앱은 실제 기상청 서버에 직접 접속해서 정보를 가져오는 것이 아니라, 미리 정해진 규칙(API)을 통해 데이터를 요청하고, 서버는 그 규칙에 맞춰 데이터를 응답합니다. 이처럼 API는 다양한 서비스와 프로그램이 서로 소통할 수 있게 해주는 다리 역할을 합니다.

API는 단순히 데이터 전달뿐 아니라, 서비스의 기능을 외부에 공개하거나, 내부 시스템끼리 효율적으로 통신하게 해주는 핵심 도구입니다. 예를 들어, 페이스북의 ‘좋아요’ 버튼을 외부 사이트에 붙이거나, 결제 시스템을 쇼핑몰에 연동할 때도 모두 API가 사용됩니다. API의 활용 범위는 웹, 모바일, 데스크탑, IoT 등 거의 모든 소프트웨어 분야에 걸쳐 있습니다.

API는 크게 두 가지로 나눌 수 있습니다. 첫째, 라이브러리 API(내부 코드에서 함수, 메서드 등으로 제공)와 둘째, 네트워크 API(HTTP, gRPC 등 네트워크를 통해 다른 시스템과 통신). 우리가 흔히 “REST API”라고 부르는 것은 두 번째, 네트워크 API에 해당합니다.

실생활 예시

• 자판기: 버튼을 누르면 음료가 나오는 것처럼, 정해진 동작(버튼)과 결과(음료)가 있습니다. 이때 버튼이 API 역할을 합니다. 사용자는 버튼(인터페이스)을 통해 원하는 결과를 얻고, 내부 동작은 몰라도 됩니다.
• 은행 ATM: 현금 인출, 잔액 조회 등 다양한 기능을 제공하는데, 각 기능은 API 호출에 비유할 수 있습니다. 사용자는 메뉴를 선택(요청)하고, ATM은 결과(응답)를 보여줍니다. 내부적으로는 은행 서버와 통신해 실제 데이터를 가져옵니다.
• 택시 호출 앱: 앱에서 출발지와 목적지를 입력하고 호출 버튼을 누르면, 서버에 API 요청이 전송되어 근처 택시가 배정됩니다. 이때 서버와 앱 사이의 통신이 모두 API를 통해 이뤄집니다.

API의 역할과 중요성

API는 개발 생산성을 높이고, 서비스의 확장성을 제공합니다. 여러 개발자가 동시에 작업할 때, API 규격만 맞추면 서로 독립적으로 개발할 수 있습니다. 또한 외부 개발자나 파트너가 내 서비스를 활용할 수 있게 하여, 생태계를 확장하는 데에도 필수적입니다.

API는 문서화가 매우 중요합니다. 명확한 API 문서가 없다면, 개발자들은 어떻게 요청해야 하고, 어떤 응답이 오는지 알 수 없어 개발이 지연되고 오류가 많아집니다. Swagger, Postman, Redoc 등 다양한 도구가 API 문서화를 도와줍니다.

API와 SDK, 라이브러리의 차이

• API: 기능을 제공하는 규약(인터페이스)
• SDK: API를 쉽게 쓸 수 있도록 도와주는 개발 도구 모음
• 라이브러리: 코드 재사용을 위한 함수/클래스 집합

API는 서비스와 서비스, 또는 서비스와 클라이언트(앱, 웹 등)를 연결하는 표준화된 다리입니다. 현대 소프트웨어 개발에서 API 설계와 활용 능력은 필수 역량입니다.

2. REST란 무엇인가?

REST의 정의

REST(Representational State Transfer)는 2000년 로이 필딩(Roy Fielding)이 논문에서 제안한 웹 아키텍처의 한 스타일입니다. REST는 “웹의 자원을 어떻게 식별하고, 접근하고, 조작할 것인가”에 대한 설계 철학이자, 실제로 웹의 확장성과 유연성을 극대화하기 위한 원칙입니다. REST는 HTTP 프로토콜의 특성을 최대한 활용하여, 누구나 이해하기 쉽고, 확장 가능한 시스템을 만들 수 있게 해줍니다.

REST의 핵심은 “자원의 상태(Representation)를 클라이언트와 서버가 주고받으며, 각 상태 변화가 HTTP 요청/응답으로 표현된다”는 점입니다. 즉, 웹의 모든 것은 ‘자원(Resource)’이고, 각 자원은 고유한 URI로 식별됩니다. 클라이언트는 HTTP 메서드(GET, POST, PUT, DELETE 등)를 사용해 자원을 조작합니다.

REST의 6가지 원칙

1. 클라이언트-서버 구조: 사용자(클라이언트)와 서버의 역할을 명확히 분리합니다. 클라이언트는 UI/UX, 서버는 데이터와 비즈니스 로직을 담당합니다. 이로 인해 각자의 개발과 배포가 독립적으로 가능합니다.
2. 무상태성(Stateless): 각 요청은 서로 독립적이어야 하며, 서버는 이전 요청의 상태를 기억하지 않습니다. 즉, 모든 요청은 필요한 정보를 모두 담아야 하며, 서버는 요청만 보고 처리할 수 있어야 합니다. 이로 인해 서버 확장(Scale-out)이 쉬워집니다.
3. 캐시 처리 가능(Cacheable): 응답은 캐시가 가능해야 하며, 이를 통해 성능을 높일 수 있습니다. 예를 들어, GET 요청에 대한 응답은 클라이언트나 중간 프록시 서버에 저장할 수 있습니다. HTTP 헤더의 Cache-Control, ETag 등이 활용됩니다.
4. 계층화된 시스템(Layered System): 중간 서버(프록시, 게이트웨이 등)를 둘 수 있어 시스템을 계층적으로 구성할 수 있습니다. 클라이언트는 중간 서버가 있는지 없는지 신경 쓰지 않고, 서버 역시 요청이 어디서 왔는지 알 필요 없습니다. 이로 인해 보안, 로드밸런싱, 캐싱 등 다양한 기능을 계층적으로 추가할 수 있습니다.
5. 일관된 인터페이스(Uniform Interface): 일관된 방법으로 자원에 접근합니다. (예: HTTP 메서드, URI 규칙, MIME 타입 등) 이 원칙 덕분에 REST API는 누구나 쉽게 사용할 수 있습니다.
6. 코드 온 디맨드(Code on Demand, 선택적): 필요시 서버가 클라이언트에 코드를 내려보낼 수 있습니다. 예를 들어, 자바스크립트 코드를 내려보내 클라이언트에서 실행하게 할 수 있습니다. 하지만 대부분의 REST API에서는 이 원칙은 잘 사용하지 않습니다.

REST의 장점과 실무 적용

REST는 단순함, 확장성, 유연성, 표준화, 다양한 언어 지원 등 많은 장점이 있습니다. 실제로 구글, 페이스북, 트위터 등 대부분의 글로벌 서비스가 RESTful API를 제공합니다. REST는 모바일 앱, 웹, IoT 등 다양한 환경에서 폭넓게 활용됩니다.

REST와 SOAP, RPC의 차이

• REST: HTTP 기반, 경량, URI+메서드, JSON/XML 등 다양한 포맷 지원
• SOAP: XML 기반, 무겁고 복잡, 엄격한 규격, 주로 엔터프라이즈 환경
• RPC: 함수 호출 개념, gRPC 등, 빠르지만 표준화가 약함

3. REST API란?

REST 원칙을 따르는 API를 REST API라고 합니다. 즉, 웹의 자원을 HTTP 프로토콜을 이용해 URL로 식별하고, HTTP 메서드(GET, POST, PUT, DELETE 등)를 통해 자원을 조작하는 방식입니다. REST API는 단순히 데이터 전달뿐 아니라, 서비스의 구조와 확장성, 유지보수성까지 크게 좌우합니다.

REST API는 다음과 같은 특징을 가집니다:

• 자원(Resource): URI로 식별되는 데이터(예: /users, /products/123)
• 행위(Verb): HTTP 메서드(GET, POST, PUT, DELETE 등)
• 표현(Representation): 데이터 포맷(JSON, XML 등)
• 상태 코드(Status Code): 요청 결과를 명확하게 알림

REST API의 예시

• GET /users : 사용자 목록을 조회
• POST /users : 새로운 사용자 등록
• GET /users/1 : ID가 1인 사용자 정보 조회
• PUT /users/1 : ID가 1인 사용자 정보 수정
• DELETE /users/1 : ID가 1인 사용자 삭제

실제 서비스에서는 이 외에도 필터링, 정렬, 페이징, 검색 등 다양한 기능이 추가됩니다. 예를 들어, GET /users?page=2&size=10&sort=name처럼 쿼리 파라미터를 활용해 원하는 데이터를 효율적으로 조회할 수 있습니다.

REST API는 프론트엔드와 백엔드가 분리된 SPA(Single Page Application) 구조에서 특히 많이 사용됩니다. 프론트엔드는 REST API를 통해 데이터를 받아와 화면을 렌더링하고, 백엔드는 REST API를 통해 외부와 통신합니다.

REST API는 오픈 API(공공 데이터, 소셜 로그인 등)로도 많이 제공되어, 외부 개발자나 파트너가 내 서비스의 일부 기능을 쉽게 활용할 수 있게 해줍니다.

4. REST API의 구성 요소

1) 자원(Resource)

REST에서 자원은 데이터를 의미합니다. 모든 자원은 고유한 URI(Uniform Resource Identifier)로 식별됩니다. 예를 들어, /users는 사용자 전체, /users/1은 ID가 1인 사용자라는 자원을 뜻합니다. 자원은 반드시 명사로 표현하며, 복수형을 사용합니다. (예: /products, /orders)

자원은 데이터베이스의 테이블과 1:1로 매핑될 수도 있지만, 꼭 그럴 필요는 없습니다. 예를 들어, /search처럼 기능 중심의 자원도 있을 수 있습니다. 하지만 REST의 원칙에서는 “자원 중심” 설계를 권장합니다.

2) 행위(Verb)

HTTP 메서드는 자원에 대한 행위를 정의합니다. 주요 메서드는 다음과 같습니다:

• GET: 데이터 조회(읽기). 서버 상태를 변경하지 않음. (예: /users)
• POST: 데이터 생성. 서버에 새로운 자원을 추가. (예: /users)
• PUT: 데이터 전체 수정. (예: /users/1)
• PATCH: 데이터 일부 수정. (예: /users/1)
• DELETE: 데이터 삭제. (예: /users/1)

메서드의 의미를 정확히 지키는 것이 RESTful API의 핵심입니다. 예를 들어, 조회는 반드시 GET, 생성은 POST를 사용해야 합니다.

3) 표현(Representation)

자원의 실제 데이터 형태를 의미합니다. 대부분의 REST API는 JSON을 사용하지만, XML, CSV 등도 가능합니다. 클라이언트는 HTTP 헤더의 Accept를 통해 원하는 포맷을 서버에 알릴 수 있습니다.

예시:

{
  "id": 1,
  "name": "홍길동"
}

4) 상태코드(Status Code)

HTTP 상태코드는 요청 결과를 숫자로 명확하게 알려줍니다. 예를 들어, 200(성공), 201(생성됨), 400(잘못된 요청), 404(자원 없음), 500(서버 오류) 등입니다. 상태코드는 클라이언트가 응답을 해석하고, 적절한 처리를 할 수 있게 해줍니다.

5) 하이퍼미디어(HATEOAS)

REST의 확장 원칙 중 하나로, 응답에 다음에 할 수 있는 행위(링크)를 포함시키는 방식입니다. 예를 들어, 사용자 조회 응답에 “수정”, “삭제” 링크를 포함할 수 있습니다. 실무에서는 필수는 아니지만, REST의 이상적인 형태입니다.

5. REST API 설계 방법

REST API를 잘 설계하는 것은 단순히 동작하는 API를 만드는 것 이상으로 중요합니다. 설계가 잘못되면 유지보수, 확장, 협업, 보안 등에서 큰 문제가 생길 수 있습니다.

1) 명확한 URI 설계

• 자원 중심으로 URI를 설계합니다. “동사” 대신 “명사”를 사용합니다. (예: /getUser 대신 /users)
• 복수형 사용: 자원은 복수형(예: /users, /products)으로 표현합니다.
• 계층 구조: 하위 자원은 URI 경로로 표현합니다. (예: /users/1/orders)
• 소문자, 하이픈(-) 사용: URI는 소문자, 단어 구분은 하이픈(-)을 사용합니다. (예: /user-profile)
• 파일 확장자 미사용: .json, .xml 등 확장자는 붙이지 않습니다. Accept 헤더로 포맷 지정

2) HTTP 메서드의 올바른 사용

• GET: 데이터 조회. 서버 상태 변경 없음. (예: /users)
• POST: 데이터 생성. (예: /users)
• PUT: 데이터 전체 수정. (예: /users/1)
• PATCH: 데이터 일부 수정. (예: /users/1)
• DELETE: 데이터 삭제. (예: /users/1)

메서드와 URI의 조합이 일관성 있게 사용되어야 합니다.

3) 일관성 있는 응답

• 응답은 JSON 형식을 주로 사용합니다. (예: { "id": 1, "name": "홍길동" })
• 상태코드를 명확하게 반환합니다. (200, 201, 204, 400, 401, 404, 500 등)
• 에러 메시지는 일관된 포맷으로 제공합니다.

예시:

{
  "status": "error",
  "message": "잘못된 요청입니다.",
  "code": 400
}

4) 예외 처리

• 잘못된 요청에는 400 Bad Request
• 권한 없음에는 401 Unauthorized
• 인증 필요에는 403 Forbidden
• 자원 없음에는 404 Not Found
• 서버 오류에는 500 Internal Server Error

5) 페이징, 정렬, 필터링

• 많은 데이터를 다룰 때는 쿼리 파라미터로 페이징, 정렬, 필터링을 지원합니다.
• 예: /users?page=2&size=10&sort=name,desc

6) API 버전 관리

• API 변경이 필요할 때는 버전을 명시합니다. (예: /api/v1/users)
• URI, 헤더, 파라미터 등 다양한 방식이 있으나, URI에 버전을 포함하는 것이 일반적입니다.

7) 문서화

• Swagger(OpenAPI), Postman, Redoc 등으로 API 문서를 자동 생성하고, 항상 최신 상태로 유지합니다.
• 예시 문서: Swagger Petstore

8) 보안

• HTTPS 필수 적용
• 인증/인가(JWT, OAuth2 등) 구현
• 입력값 검증, Rate Limit(요청 제한), CORS 설정 등

6. REST API의 장점과 단점

장점

• HTTP 기반이므로 웹에서 쉽게 사용 가능하고, 방화벽, 프록시 등 기존 인프라를 그대로 활용할 수 있습니다.
• 언어/플랫폼 독립적: Java, Python, Node.js, Kotlin 등 어떤 언어로도 구현 가능
• 구조가 단순: URI+메서드+상태코드로 일관성 유지
• 확장성: 서버 확장, 마이크로서비스 구조에 적합
• 캐시, 프록시, 로드밸런서 등 웹 인프라 활용 용이
• 문서화, 자동화 도구 풍부: Swagger, Postman, Redoc 등

단점

• 엄격한 표준 부재: REST 원칙 해석이 달라, 설계가 제각각일 수 있음
• 복잡한 트랜잭션 처리 한계: 여러 자원을 동시에 변경하는 복잡한 작업은 어렵고, 2PC 등 별도 패턴 필요
• 보안/인증 별도 구현: JWT, OAuth2 등 직접 구현해야 하며, 실수 시 보안 취약점 발생 가능
• 버전 관리 어려움: API가 많아질수록 버전 관리가 복잡
• HATEOAS 등 REST의 이상적인 원칙은 실무에서 잘 안 씀

7. REST API 실전 예시

실전 예시를 통해 REST API의 설계, 구현, 테스트, 문서화까지 전체 흐름을 익혀봅시다.

예시: 간단한 사용자 관리 API

1) 사용자 목록 조회

• 요청: GET /users
• 응답: [ { "id": 1, "name": "홍길동" }, { "id": 2, "name": "김철수" } ]

2) 사용자 등록

• 요청: POST /users
• 요청 본문: { "name": "이영희" }
• 응답: { "id": 3, "name": "이영희" }

3) 사용자 정보 수정

• 요청: PUT /users/3
• 요청 본문: { "name": "이영희(수정)" }
• 응답: { "id": 3, "name": "이영희(수정)" }

4) 사용자 삭제

• 요청: DELETE /users/3
• 응답: 상태코드 204(No Content)

5) 사용자 검색, 페이징, 정렬

• 요청: GET /users?name=홍&page=1&size=10&sort=id,desc
• 응답: 페이징된 사용자 목록

실제 코드 예시 (Kotlin + Spring Boot)

data class User(val id: Long, val name: String)

data class UserDto(val name: String)

@Service
class UserService {
    private val users = mutableListOf(
        User(1, "홍길동"),
        User(2, "김철수")
    )
    fun getAllUsers(): List<User> = users
    fun createUser(user: User): User {
        val newUser = user.copy(id = (users.maxOfOrNull { it.id } ?: 0) + 1)
        users.add(newUser)
        return newUser
    }
    fun getUser(id: Long): User = users.first { it.id == id }
    fun updateUser(id: Long, user: User): User {
        val idx = users.indexOfFirst { it.id == id }
        val updated = user.copy(id = id)
        users[idx] = updated
        return updated
    }
    fun deleteUser(id: Long) { users.removeIf { it.id == id } }
}

@RestController
@RequestMapping("/users")
class UserController(val userService: UserService) {
    @GetMapping
    fun getUsers(): List<User> = userService.getAllUsers()

    @PostMapping
    fun createUser(@RequestBody user: User): User = userService.createUser(user)

    @GetMapping("/{id}")
    fun getUser(@PathVariable id: Long): User = userService.getUser(id)

    @PutMapping("/{id}")
    fun updateUser(@PathVariable id: Long, @RequestBody user: User): User = userService.updateUser(id, user)

    @DeleteMapping("/{id}")
    fun deleteUser(@PathVariable id: Long) = userService.deleteUser(id)
}

Postman으로 테스트하기

Postman은 REST API를 쉽게 테스트할 수 있는 대표적인 도구입니다.

• 각 요청을 직접 보내보고, 응답을 확인해보세요.
• 다양한 환경 변수, 인증, 자동화 테스트, 문서화 기능도 제공합니다.
• 실제로 실무에서는 Postman으로 API를 설계, 테스트, 문서화, 자동화까지 모두 처리하는 경우가 많습니다.
• 예시: Postman에서 GET/POST/PUT/DELETE 요청을 만들어보고, 응답을 확인하며 API의 동작을 검증할 수 있습니다.
• Postman Collection을 만들어 팀원과 공유하면 협업이 훨씬 편리해집니다.

Swagger(OpenAPI)로 문서화하기

Swagger는 REST API의 명세를 작성하고, 자동으로 문서화 및 테스트 UI를 제공합니다.

• Spring Boot에서는 springdoc-openapi, springfox 등 라이브러리를 통해 자동 문서화가 가능합니다.
• Swagger UI를 통해 API를 직접 테스트할 수도 있습니다.
• 공식 문서: Swagger OpenAPI

8. REST API 설계시 주의사항

• URI, 메서드, 응답 형식의 일관성 유지: 팀 내/외부 개발자 모두가 쉽게 이해할 수 있도록 규칙을 정하고 지켜야 합니다.
• 보안(인증, 인가) 반드시 고려: JWT, OAuth2, HTTPS 적용, 입력값 검증, Rate Limit, CORS 등
• 문서화(Swagger, Postman 등)로 API 사용법 명확히 제공: 항상 최신 상태 유지
• 버전 관리(v1, v2 등) 필요시 URI에 포함: 하위 호환성, 점진적 개선을 위해 필수
• 테스트 자동화: JUnit, MockMvc, RestAssured 등으로 API 테스트 자동화
• 에러 및 예외 처리: 일관된 에러 포맷, 상세 메시지 제공
• 성능 최적화: 캐싱, 압축, 페이징, 비동기 처리 등
• 모니터링/로깅: API 호출 로그, 에러 로그, 성능 지표 수집
• 배포/운영: 무중단 배포, 롤백 전략, 장애 대응 체계 마련

9. REST API와 RESTful의 차이

• RESTful: REST의 6가지 원칙(클라이언트-서버, 무상태성, 캐시, 계층화, 일관성, 코드 온 디맨드)을 최대한 잘 지킨 API. 예를 들어, URI/메서드/상태코드/응답포맷이 모두 표준에 맞게 설계됨.
• REST API: REST 원칙을 일부만 따르거나, 실무적 타협이 들어간 API. 예를 들어, 일부 동사형 URI, 상태코드 미사용 등. 하지만 여전히 REST 스타일의 API로 분류됨.
• 실무에서는 “RESTful”을 목표로 하지만, 현실적으로 100% 지키기 어려운 경우가 많음.

10. 결론

REST API는 현대 웹 개발에서 가장 널리 사용되는 통신 방식입니다. 초보자도 개념과 원리를 이해하면 다양한 서비스 개발에 쉽게 활용할 수 있습니다. 직접 실습해보고, 다양한 예제를 따라 해보는 것이 가장 좋은 공부 방법입니다. 실무에서는 설계, 구현, 테스트, 문서화, 보안, 운영까지 REST API의 전 과정을 경험해보는 것이 중요합니다. 공식 문서와 다양한 오픈소스 예제, 실습 도구(Postman, Swagger 등)를 적극 활용해보세요.

---

• 참고자료: REST API 제대로 알고 사용하기, MDN REST, Spring 공식문서, Swagger Petstore