[API] RESTful API 정리 (개념부터 예제까지)

🔘 RESTful API란?

RESTful API는 REST(Representational State Transfer) 원칙을 따르는 API를 의미합니다.
REST는 분산 시스템에서 자원을 효율적으로 관리하고 상호작용할 수 있도록 설계된 아키텍처 스타일입니다.

---

⚪ REST의 기본 원칙

RESTful API를 설계할 때 따라야 할 주요 원칙은 다음과 같습니다.

1. 클라이언트-서버 구조 (Client-Server Architecture)
클라이언트와 서버는 분리되어야 하며, 클라이언트는 서버의 리소스를 요청하고, 서버는 요청을 처리하여 응답합니다.

2. 무상태성 (Statelessness)
서버는 요청을 처리할 때 이전 상태를 저장하지 않습니다.
즉, 각 요청은 독립적이며, 필요한 모든 정보를 포함해야 합니다.

3. 캐시 가능 (Cacheable)
서버의 응답은 캐시될 수 있어야 하며, 이를 통해 성능을 최적화할 수 있습니다.

4. 계층화된 시스템 (Layered System)
클라이언트는 서버의 내부 구조를 알 필요 없이 요청을 보낼 수 있어야 합니다.
또한 서버는 여러 계층으로 구성될 수 있으며, 각 계층은 독립적으로 동작해야 합니다.

5. 일관된 인터페이스 (Uniform Interface)
RESTful API는 일관된 방식으로 자원(Resource)을 정의하고 접근해야 합니다.
이를 위해 보통 아래와 같은 설계를 따릅니다.

• URI를 통해 자원 식별
  • 예: /users/123 (ID가 123인 사용자)
• HTTP 메서드 사용
  • GET: 리소스 조회
  • POST: 리소스 생성
  • PUT: 리소스 전체 수정
  • PATCH: 리소스 부분 수정
  • DELETE: 리소스 삭제
• 표준화된 응답 형식(JSON 사용 권장)

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

---

⚪ RESTful API 설계 예제

1. 사용자(User) 관리 API

기능	HTTP 메서드	엔드포인트	설명
사용자 목록 조회	GET	/users	모든 사용자 조회
사용자 정보 조회	GET	/users/{id}	특정 사용자 조회
사용자 생성	POST	/users	새 사용자 추가
사용자 수정	PUT	/users/{id}	전체 정보 수정
사용자 부분 수정	PATCH	/users/{id}	일부 정보 수정
사용자 삭제	DELETE	/users/{id}	사용자 삭제

2. 예제 코드
다음은 users 엔드포인트에서 사용자를 조회하고, 생성하고, 수정하고, 삭제하는 예제입니다.

1) 모든 사용자 조회 (GET /users)

• 요청

curl -X GET "https://api.example.com/users"

• 응답

[
  {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com"
  },
  {
    "id": 2,
    "name": "Bob",
    "email": "bob@example.com"
  }
]

2) 특정 사용자 조회 (GET /users/{id})

• 요청

curl -X GET "https://api.example.com/users/1"

• 응답

{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com"
}

3) 새 사용자 추가 (POST /users)

• 요청

curl -X POST "https://api.example.com/users" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Charlie",
       "email": "charlie@example.com"
     }'

• 응답

{
  "id": 3,
  "name": "Charlie",
  "email": "charlie@example.com"
}

4) 사용자 정보 수정 (PUT /users/{id})

• 요청

curl -X PUT "https://api.example.com/users/3" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Charlie Brown",
       "email": "charlie.brown@example.com"
     }'

• 응답

{
  "id": 3,
  "name": "Charlie Brown",
  "email": "charlie.brown@example.com"
}

5) 사용자 일부 정보 수정 (PATCH /users/{id})

• 요청

curl -X PATCH "https://api.example.com/users/3" \
     -H "Content-Type: application/json" \
     -d '{
       "email": "new.charlie@example.com"
     }'

• 응답

{
  "id": 3,
  "name": "Charlie Brown",
  "email": "new.charlie@example.com"
}

6) 사용자 삭제 (DELETE /users/{id})

• 요청

curl -X DELETE "https://api.example.com/users/3"

• 응답

{
  "message": "User deleted successfully"
}

---

⚪ RESTful API 설계 시 고려할 점

1. 명확한 URL 구조 사용

• RESTful API는 직관적이고 명확한 URL 구조를 가져야 합니다.

  GET /users/123/posts  →  ID가 123인 사용자의 게시글 목록 조회
  GET /products/456/reviews  →  ID가 456인 상품의 리뷰 목록 조회

• URL에는 동작(동사)이 아닌 리소스(명사) 를 사용해야 합니다.
  /getUsers 🔴 잘못된 예시
  /users      🟢 올바른 예시

2. 적절한 HTTP 상태 코드 사용
RESTful API는 요청 처리 결과를 HTTP 상태 코드로 명확하게 표현해야 합니다.

상태 코드	의미	설명
200 OK	요청 성공	조회 성공
201 Created	리소스 생성 성공	POST 요청 후 새 리소스 생성됨
204 No Content	요청 성공 (응답 본문 없음)	DELETE 요청 성공 후 응답 없음
400 Bad Request	잘못된 요청	클라이언트의 요청 오류
401 Unauthorized	인증 필요	인증되지 않은 사용자 요청
403 Forbidden	접근 권한 없음	인증되었으나 권한이 없는 경우
404 Not Found	요청한 리소스 없음	존재하지 않는 데이터 요청
500 Internal Server Error	서버 내부 오류	예기치 않은 서버 오류

3. 응답 메시지의 일관성 유지

• 모든 응답은 JSON 형식으로 제공하는 것이 일반적입니다.
• 응답 메시지의 필드명은 일관된 네이밍 규칙을 따라야 합니다.

(예시)
{
  "status": "success",
  "data": {
    "id": 1,
    "name": "Alice",
    "email": "alice@example.com"
  }
}

4. 보안 고려 (인증 및 인가)

• API 호출 시 인증(Authentication)과 인가(Authorization) 를 고려해야 합니다.
• 일반적인 인증 방식
  • JWT (JSON Web Token)
  • OAuth 2.0
  • API Key 인증
  • HTTPS 사용 필수
• API 통신을 암호화하기 위해 반드시 HTTPS를 사용해야 합니다.

---

⚪ 결론

RESTful API는 웹 서비스를 설계하는 표준적인 방식으로, 일관성 있고 확장성이 뛰어난 API를 만들 수 있도록 도와줍니다.
REST 원칙을 따르고, 적절한 HTTP 메서드 및 상태 코드를 활용하면 보다 직관적이고 효율적인 API를 설계할 수 있습니다.