<목차>

• RESTful API
• 고유 식별자(ID)
• 쿼리 파라미터

---

1. RESTful API

RESTful API는 REST(Representational State Transfer)라는 아키텍처 스타일을 따르는 API를 의미한다. REST는 웹 상에서 데이터를 주고받는 방식에 대한 일종의 설계 원칙으로, 주로 HTTP 프로토콜을 기반으로 하여 통신한다. RESTful API는 다음과 같은 원칙을 준수하여 클라이언트와 서버 간에 데이터를 주고받는 API를 설계하는 것이다.

<RESTful API의 설계 원칙>

1. 자원의 명확한 URI 설계

• URI는 자원을 명확히 표현해야 하며, 직관적으로 이해될 수 있어야 한다. 일반적으로 동사가 아닌 명사로 표현된다.

• 이때 모든 리소스를 복수형으로 명명하면, 사용자가 API를 사용할 때 예측 가능성을 높이고 혼동을 줄일 수 있다. (예시: /users, /products, /orders)

2. HTTP 메서드의 의미적 사용

• CRUD 작업을 수행할 때, HTTP 메서드를 정확히 사용해야 한다.

  • GET: 자원을 조회할 때 사용.
    GET /users: 모든 사용자 목록을 가져옴
GET /users/123: 특정 ID(123)를 가진 사용자를 가져옴
  • POST: 새로운 자원을 생성할 때 사용.
    POST /users: 새로운 사용자 생성.
  • PUT: 자원을 수정할 때 사용. (전체 업데이트를 의미)
    PUT /users/123: ID 123의 사용자 정보 업데이트
  • PATCH: 자원의 일부만 수정할 때 사용.
  • DELETE: 자원을 삭제할 때 사용.
    DELETE /users/123: ID 123의 사용자 삭제

3. 자원 상태를 표현하는 응답 구조

• RESTful API는 일반적으로 JSON 또는 XML 형식으로 데이터를 주고받지만, 주로 JSON이 더 많이 사용된다.

1. HTTP 헤더 (Headers)
   : 요청 및 응답에 대한 메타데이터를 포함하는 부분이다.

---

• 요청 헤더
  • Content-Type: 요청 본문의 데이터 형식 (예: application/json)
  • Authorization: 인증 토큰
• 응답 헤더
  • Content-Type: 응답 본문의 데이터 형식 (예: application/json)
  • Location: 새로 생성된 자원의 URI (POST 요청 후에 주로 사용됨)
  • Cache-Control: 캐싱 지침

2. 요청 본문 (Request Body)
   : 클라이언트가 서버에 데이터를 전송할 때 포함되는 내용이다. 보통 POST, PUT, PATCH 등의 메서드에서 사용된다.

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

3. 응답 본문 (Response Body)
   : 서버가 클라이언트의 요청에 대해 반환하는 데이터이다. 주로 JSON, XML 등의 형식으로 자원 상태를 표현한다.

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

4. 상태 코드 활용

• 응답 시에는 상황에 맞는 HTTP 상태 코드를 사용하여 클라이언트가 요청의 성공 또는 실패를 명확하게 알 수 있도록 해야 한다.
• 상태 코드는 HTTP 응답 헤더(Response Header)의 첫 번째 줄에 포함된다.

<HTTP 응답 헤더 예시>

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-cache

<상태 코드>

• 200 O: 요청이 성공적으로 처리됨.
• 201 Created: 요청이 성공적으로 처리되어 새 자원이 생성됨.
• 204 No Content: 요청이 성공적으로 처리되었지만 반환할 콘텐츠가 없음.
• 400 Bad Request: 클라이언트의 요청이 잘못되었음.
• 401 Unauthorized: 인증이 필요한 요청이나 인증 정보가 잘못됨.
• 403 Forbidden: 요청이 서버에 의해 거부됨.
• 404 Not Found: 요청한 자원이 존재하지 않음.
• 500 Internal Server Error: 서버 내부에서 오류가 발생했음.

---

2. 고유 식별자(ID)

• /users/{id}에서 id는 특정 사용자를 식별하는 고유한 식별자(ID, Identifier)이다.
• ID는 보통 데이터베이스에서 해당 사용자의 레코드(행)를 나타내는 고유한 값이며, RESTful API에서 자원을 구체적으로 식별하는 데 사용된다.

<id의 의미>

• 각 사용자는 고유한 id를 가진다. id는 숫자일 수도 있고, 문자열일 수도 있다. 이것을 통해 서버는 특정한 자원을 구별할 수 있다.
• id는 주로 특정한 자원을 조회하거나 수정, 삭제할 때 사용된다.
  • GET /users/123 (ID가 123인 사용자의 정보를 가져옴)

📌 개체가 서로 다른 종류의 리소스(예: 사용자와 게시물)일 때는 ?

• RESTful API에서 리소스를 명확히 구분하기 위해서는 각 리소스마다 고유한 URI 경로를 사용하는 것이 중요하다.
  사용자 리소스: /users/{userId}
게시물 리소스: /posts/{postId}

---

3. 쿼리 파라미터

• 일부 API에서는 고유 식별자를 모를 때 특정 조건으로 검색할 수 있는 기능을 제공한다. 예를 들어, 이메일, 사용자명 등으로 검색할 수 있는 쿼리 파라미터를 사용할 수 있다.
• 쿼리 파라미터는 주로 GET 요청에서 사용되지만, POST 요청에서도 데이터 전송을 위해 사용할 수 있습니다.

<쿼리 파라미터의 구조>

• ?: 쿼리 파라미터의 시작을 나타낸다.
• key=value: 각각의 파라미터를 키-값 쌍으로 표현한다.
• &: 여러 개의 파라미터를 구분한다.
  • 예: /users?age=25&city=Seoul (나이가 25세이고, 서울에 사는 사용자를 조회)

<쿼리 파라미터의 사용 예시>
1. 필터링

• 데이터베이스 쿼리에서 특정 조건을 추가할 때 사용한다.

  예: /users?age=25&city=Seoul
  (나이가 25세이고, 서울에 사는 사용자를 조회)

2. 페이징

• 결과를 페이지 단위로 나누어 표시할 때 사용한다.

  예: /products?page=2&size=10
  (두 번째 페이지의 제품 목록을 10개씩 조회)

3. 정렬

• 결과를 정렬하는 데 사용한다.

  예: /orders?sort=createdDate&direction=desc
  (생성일 기준으로 내림차순으로 정렬된 주문 목록을 조회)

📌 쿼리 파라미터와 경로 파라미터의 차이

• 쿼리 파라미터
  • URL의 ? 다음에 위치하며, 선택적인 추가 정보를 전달한다.
  • 예: /users?age=30
• 경로 파라미터
  • URL의 경로에 포함되어 리소스를 식별한다.
  • 예: /users/123