[TECH-QA] RESTful API이란?

Posted 5 months Updated 5 months

By 베짱이가 되고싶은 개미。

RESTful API(Representational State Transfer API)는 웹 서비스를 구축하기 위한 설계 방식 중 하나로, REST라는 아키텍처 스타일을 따르는 API로, 주로 HTTP 프로토콜을 기반으로하는 웹 서비스 아키텍처입니다. 자원, 메소드, 메시지 등을 정의하여 클라이언트-서버 간의 통신을 가능하게 합니다.

메시지(Message)

메시지는 클라이언트와 서버 간의 통신에서 전달되는 데이터의 내용을 나타냅니다. RESTful API에서 메시지는 요청(Request)과 응답(Response)로 구분됩니다.

요청 메시지

요청 메시지는 클라이언트가 서버로 보내는 데이터입니다. 이 데이터에는 요청의 목적과 함께 필요한 정보가 포함될 수 있습니다. 주로 JSON 형식으로 데이터가 전송됩니다. 요청 메시지에는 요청하는 자원의 식별, 자원의 상태 변경을 위한 데이터, 요청하는 작업의 종류(메소드) 등이 포함될 수 있습니다.

📝 요청(Request)

ID가 123인 사용자의 정보를 조회 : GET /users/123

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com"
}

새로운 사용자 생성 : POST /users

{
  "name": "Jane Doe",
  "email": "jane@example.com"
}

응답: 201 Created (성공 시)

응답 메시지

응답 메시지는 서버가 클라이언트로 보내는 데이터입니다. 클라이언트의 요청에 대한 응답으로 성공 여부, 처리된 데이터, 또는 오류 정보를 클라이언트에게 전달합니다. 일반적으로 HTTP 상태 코드와 함께 JSON 형식으로 반환되며, 상황에 따라 다양한 구조를 가질 수 있습니다. 마찬가지로 주로 JSON 형식으로 데이터가 전송됩니다.

상황: 사용자가 특정 리소스를 성공적으로 조회했을 때
HTTP 상태 코드: 200 OK

📝 예제) ID가 123인 사용자를 조회

{
  "status": "success",
  "data": {
    "id": 123,
    "name": "John Doe",
    "email": "john@example.com",
    "created_at": "2025-01-01T10:00:00Z"
  },
  "message": "User retrieved successfully"
}

상황: 새로운 리소스가 성공적으로 생성되었을 때
HTTP 상태 코드: 201 Created

📝 예제) 새로운 사용자를 추가

{
  "status": "success",
  "data": {
    "id": 124,
    "name": "Jane Doe",
    "email": "jane@example.com",
    "created_at": "2025-03-11T09:00:00Z"
  },
  "message": "User created successfully",
  "location": "/users/124"
}

location: 새로 생성된 리소스의 URI를 나타냄 (선택적).

📝 서버에서 응답 메시지 설계 팁

일관성 유지: 성공/오류 응답 형식을 일관되게 설계 (예: 항상 status, data, message 필드 사용).
상태 코드 활용: 적절한 HTTP 상태 코드를 사용해 클라이언트가 응답을 쉽게 해석하도록 도움.
오류 상세 제공: 오류 발생 시 error 객체에 구체적인 정보(코드, 메시지, 세부사항)를 포함해 디버깅 용이성을 높임.
필요한 데이터만 반환: 클라이언트가 필요로 하는 정보만 제공해 오버페칭(over-fetching)을 방지.

자원(Resource)

자원은 RESTful API의 핵심 개념 중 하나입니다. URI(Uniform Resource Identifier)란 웹상의 자료의 id 즉, 내가 올린 블로그 글의 특정 id를 입력해줘야 글을 볼수 있는 것처럼 URI는 인터넷 자원을 나타내는 서버에 있는 정보(고유 식별자)의 표현입니다.
일반적으로 웹에서는 URI를 사용하여 아래와 같이 자원을 식별합니다.

/todos ---- 할일 목록이라는 자원
/todos/1 ---- ID가 1인 특정 할일 자원

메소드(Method) 메시지

메소드 메시지는 클라이언트가 서버에게 요청하는 작업의 종류를 나타냅니다. RESTful API에서는 주로 다음과 같은 네 가지 메소드를 사용합니다.

GET: 서버에서 자원을 가져오기 위해 사용됩니다. 클라이언트가 서버에게 특정 자원에 대한 정보를 요청할 때 사용됩니다. 예를 들어, /todos에 GET 요청을 보내면 모든 할일 목록을 가져올 수 있습니다.
POST: 서버에 새로운 자원을 생성하기 위해 사용됩니다. 클라이언트가 서버에게 새로운 자원을 추가하려는 경우 사용됩니다. 예를 들어, /todos에 POST 요청을 보내면 새로운 할일을 추가할 수 있습니다.
PUT: 서버의 자원을 수정하기 위해 사용됩니다. 클라이언트가 서버에게 특정 자원을 수정하려는 경우 사용됩니다. 예를 들어, /todos/1에 PUT 요청을 보내면 ID가 1인 할일을 수정할 수 있습니다.
DELETE: 서버에서 자원을 삭제하기 위해 사용됩니다. 클라이언트가 서버에게 특정 자원을 삭제하려는 경우 사용됩니다. 예를 들어, /todos/2에 DELETE 요청을 보내면 ID가 2인 할일을 삭제할 수 있습니다.

REST의 주요 특징

📝 클라이언트-서버 구조 (Client-Server)

클라이언트와 서버가 명확히 분리되어 있습니다. 클라이언트는 요청을 보내고, 서버는 이에 대한 응답을 제공합니다. 이로 인해 각 구성 요소가 독립적으로 발전할 수 있습니다.

📝 유니폼 인터페이스(일관적인 인터페이스)

REST API는 리소스(데이터)를 URI로 식별하고, HTTP 메서드(GET, POST, PUT, DELETE 등)를 통해 조작합니다. 이를 통해 단순하고 일관된 접근 방식을 제공합니다.

예: GET /users/123 (특정 사용자 조회), POST /users (사용자 생성).

📝 무상태성(Statelessness)

REST API는 상태를 관리하지 않는 stateless한 특성을 가집니다. 상태가 없다는 것은 클라이언트가 서버의 요청을 보낼 때 각 요청은 독립적으로 처리되며, 서버는 이전 요청의 상태를 기억하지 않습니다. 클라이언트는 필요한 모든 정보를 요청에 포함해야 합니다. 이는 서버의 부하를 줄이고, 확장성을 높이는데 도움이 됩니다. HTTP는 기본적으로 상태가 없는 프로토콜 입니다. 따라서 HTTP를 사용하는 웹 애플리케이션은 기본적으로 상태가 없는 구조를 따릅니다.

📝 캐시 가능 (Cacheable)

응답 데이터는 캐시 가능 여부를 명시할 수 있어, 클라이언트나 중간 서버가 동일한 요청에 대해 이전 응답을 재사용할 수 있습니다. 이는 성능을 향상시킵니다.

📝 계층화 시스템 (Layered System)

클라이언트는 서버와 직접 통신하는지, 아니면 프록시나 게이트웨이 같은 중간 계층을 거치는지 알 필요가 없습니다. 이는 보안과 확장성을 높입니다.

📝 리소스 중심 (Resource-Based)

모든 데이터는 리소스로 표현되며, 클라이언트는 리소스를 조작합니다. 리소스는 JSON, XML 등의 형식으로 표현됩니다.

📝 HTTP 프로토콜 활용

REST는 주로 HTTP를 기반으로 동작하며, 상태 코드(200 OK, 404 Not Found 등)를 사용해 요청의 성공/실패 여부를 전달합니다.

📝 기타

확장성: Stateless와 계층화 덕분에 서버 부하를 분산하기 쉽습니다.
유연성: 다양한 클라이언트(웹, 모바일 등)에서 사용 가능합니다.
단순성: 직관적인 설계로 개발과 유지보수가 용이합니다.

이와 같은 특징들로 REST API는 인터넷 상의 자원을 표현하고, 다양한 플랫폼 및 언어 간의 통신을 간소화하며, 확장성 있는 시스템을 구축하는 데 사용됩니다.