RESTful API란 무엇인가?

1. RESTful API란 무엇인가?

Q: RESTful API란 무엇인가요?

• RESTful API는 Representational State Transfer (REST)라는 아키텍처 스타일을 따르는 API입니다.

• REST는 웹 기반 애플리케이션의 설계 원칙을 정의하며, 클라이언트와 서버 간의 통신을 간단하고 확장 가능하게 만듭니다.

• RESTful API는 리소스를 기반으로 한 URL을 사용하고, HTTP 메서드(GET, POST, PUT, DELETE 등)를 통해 리소스의 상태를 관리합니다.

Q: RESTful API의 주요 특징은 무엇인가요?

• 무상태성(Stateless): 각 요청은 독립적이며, 서버는 클라이언트의 상태를 유지하지 않습니다. 요청마다 필요한 모든 정보가 포함되어야 합니다.

• 리소스 기반 URL: URL은 리소스를 명확히 식별합니다. 예를 들어, /users/123는 id가 123인 사용자를 가리킵니다.

• HTTP 메서드 사용: 각 메서드는 특정 작업을 수행하는 데 사용됩니다. 예를 들어, GET은 데이터를 조회하고, POST는 데이터를 생성합니다.

• 표현(JSON, XML 등): 서버는 클라이언트에 리소스를 다양한 형태로 표현하여 전달합니다. 가장 일반적인 형태는 JSON입니다.

---

2. Request Parameters와 Request Body의 차이점

Q: Request Parameters와 Request Body의 차이점은 무엇인가요?

Request Parameters와 Request Body는 API 요청 시 데이터를 전달하는 두 가지 주요 방법으로, 각각의 용도와 적절한 사용 시점이 다릅니다.

Request Parameters (Query Parameters):

• 위치: URL의 끝에 ?key=value 형식으로 붙습니다. 여러 값을 전달할 때는 &로 구분합니다.
• 용도: 주로 리소스의 조회나 필터링에 사용됩니다. 이 값들은 서버에서 리소스의 상태를 변경하지 않고, 특정 조건에 맞는 데이터를 가져오는 데 도움을 줍니다.
• 예시: GET /api/users?id=123&status=active
  • 이 예시에서 id=123과 status=active는 특정 사용자를 조회하거나 상태에 따라 필터링하기 위한 조건입니다.

Request Body:

• 위치: HTTP 요청의 본문에 포함됩니다. 보통 JSON, XML, 혹은 다른 포맷으로 데이터를 전달합니다.
• 용도: 주로 데이터를 생성하거나 수정할 때 사용됩니다. 이는 서버에서 리소스의 상태를 변경하는데 적합합니다.
• 예시: POST /api/users

  {
    "name": "John",
    "age": 30,
    "city": "Seoul"
  }

  • 이 요청은 새로운 사용자를 생성하기 위해 필요한 데이터를 본문에 포함시킵니다.

---

Q: 언제 Request Parameters와 Request Body를 사용해야 하나요?

이 질문은 API 설계에서 매우 중요한 부분입니다. Request Parameters와 Request Body의 차이를 이해하고, 그에 맞게 데이터를 전달하는 것이 필요합니다.

---

• 리소스 식별 및 필터링: 만약 요청에서 특정 리소스를 식별하거나 필터링할 필요가 있다면, Request Parameters 또는 URL Path를 사용해야 합니다.

• 예를 들어, 특정 사용자의 프로필을 업데이트하거나 조회할 때 id와 같은 식별자를 URL에 포함시키는 것이 일반적입니다.

  • 예시: GET /api/users/123 - id가 123인 사용자의 정보를 조회
  • 예시: POST /api/users/123/profile - id가 123인 사용자의 프로필을 생성 또는 업데이트

• 데이터 생성 및 수정: 반면에, 서버에 저장하거나 업데이트할 데이터는 Request Body에 포함되어야 합니다. 여러 필드를 포함하는 데이터 구조(DTO)로 묶어서 전송하는 것이 일반적입니다. 이는 서버에서 이 데이터를 받아 처리하고 리소스를 생성하거나 수정하는 데 사용됩니다.

  • 예시:

    {
      "name": "John",
      "age": 30,
      "city": "Seoul"
    }

    • 이 데이터는 새로운 사용자를 생성하기 위해 POST 요청의 Body에 포함됩니다.
  
  

---

Q: 만약 저장할 값이 하나의 값이라면 어떻게 해야 하나요? 그리고 여러 값일 때는요?

• 하나의 값을 저장할 때: 만약 서버에 저장해야 할 데이터가 하나뿐이라면, Request Body에 해당 값을 단독으로 포함시킬 수 있습니다. 이 경우에도 Request Parameters는 주로 리소스 식별에 사용됩니다.

  • 예시: POST /api/users/123/status

    {
      "status": "active"
    }

    • 여기서 id가 123인 사용자의 상태를 업데이트하기 위해 status 필드 하나만을 Request Body로 전송합니다.
  
  

• 여러 값을 저장할 때: 만약 저장해야 할 값이 여러 개라면, 해당 값들을 하나의 객체(DTO)로 묶어 Request Body에 포함시키는 것이 가장 적절합니다. 이때 리소스를 식별하는 id는 여전히 URL에 포함됩니다.
  • 예시: POST /api/users/123/profile

    {
      "name": "Jane",
      "email": "jane@example.com",
      "phone": "010-1234-5678",
      "address": "Seoul, Korea"
    }

    • 이 요청은 id가 123인 사용자의 프로필 정보를 업데이트하기 위한 것입니다. name, email, phone, address와 같은 여러 필드를 포함하는 데이터가 Request Body에 전달됩니다.

---

Q: 그러면 id로 리소스를 식별하고, 저장할 값이 여러 개일 때 어떻게 해야 하나요?

이 경우 가장 일반적인 접근 방식은 id를 URL Path나 Request Parameters에 포함시키고, 저장해야 할 여러 값은 Request Body에 하나의 DTO로 묶어 전송하는 것입니다.

예를 들어, 사용자의 프로필 정보를 업데이트하려는 상황이라면:

• URL: POST /api/users/123/profile

  • 여기서 123은 id로 특정 사용자를 식별합니다.

• Request Body:

  {
    "name": "Jane",
    "email": "jane@example.com",
    "phone": "010-1234-5678",
    "address": "Seoul, Korea"
  }

  • 이 Body는 업데이트하려는 여러 필드의 값을 포함합니다.

이 방식은 RESTful API의 설계 원칙을 따르면서도, 명확하고 일관된 데이터를 전송할 수 있게 해줍니다. 각각의 값이 어떤 용도로 사용되는지 명확히 구분할 수 있기 때문에, API를 사용하는 사람에게도 이해하기 쉽고 유지보수하기도 용이합니다.

---

3. RESTful API를 위한 URL 설계 방식

Q: RESTful API에서 URL은 어떻게 설계해야 하나요?

RESTful API에서는 URL을 리소스 중심으로 설계하는 것이 중요합니다. URL은 행동(동사)이 아닌 리소스(명사)를 나타내야 하며, HTTP 메서드를 통해 행동을 구분합니다.

Q: 유저 프로필을 생성하는 API를 설계할 때, URL은 어떻게 해야 하나요?

예를 들어, 유저 프로필을 생성하는 API를 설계한다고 가정해 보겠습니다.

• 잘못된 예시: POST /user/create-profile

  • 여기서 create-profile은 동사를 포함하고 있어 RESTful하지 않습니다.

• 올바른 예시: POST /user/profile

  • 이 경우, profile은 리소스를 나타내며, POST 메서드는 프로필을 생성하는 동작을 나타냅니다.

---

Q: 다른 예시들도 있을까요?

• 조회: GET /user/123/profile - id가 123인 사용자의 프로필을 조회
• 수정: PUT /user/123/profile - id가 123인 사용자의 프로필을 수정
• 삭제: DELETE /user/123/profile - id가 123인 사용자의 프로필을 삭제

이처럼, RESTful API에서는 URL은 리소스를 나타내고, HTTP 메서드는 해당 리소스에 대해 수행할 작업을 나타내도록 설계하는 것이 중요합니다.

---

이러한 내용들을 잘 숙지하며 RESTful API 설계에서의 Request Parameters와 Request Body의 올바른 사용법과 URL 설계 방식에 대해 명확하게 이해하면서 사용하는게 중요합니다.