지난주에는 ERD 설계를 통해 데이터베이스 구조를 설계하며 프로젝트의 데이터를 정의했습니다.
이번 주차에서는 데이터를 활용하기 위한 API 설계를 다룹니다.
API는 단순히 클라이언트와 서버 간의 통신을 위한 도구가 아닙니다.
API 설계는 프로젝트의 기능을 구체화하고, 팀원 간 협업을 원활히 하기 위한 로드맵을 만드는 작업입니다.
왜 API 설계가 중요한가요?
1️⃣ 프로젝트의 큰 틀을 잡는 과정
- API는 데이터베이스와 함께 프로젝트의 핵심 구조를 형성합니다.
- 명확한 설계를 통해 데이터 흐름을 효율적으로 관리할 수 있습니다.
2️⃣ 협업의 가이드라인 제공
- API 명세서를 통해 프론트엔드, 백엔드, 기획자 모두가 같은 방향으로 작업할 수 있습니다.
- 이를 통해 기능 구현 단계에서 발생할 수 있는 혼란을 최소화할 수 있습니다.
3️⃣ 확장성과 유지보수성 확보
- 설계 초기부터 API 구조를 체계적으로 정의하면, 새로운 기능 추가나 변경 시에도 유연하게 대응할 수 있습니다.
API 설계에서 가장 중요한 두 가지
1️⃣ API Endpoint 설계
- 각 기능이 어떤 경로(URL)를 통해 호출될지 정의.
- 명확하고 직관적인 경로로 설계해야 협업과 유지보수가 쉬워집니다.
2️⃣ 요청(Request)과 응답(Response) 데이터 설계
- 클라이언트가 서버에 전달할 데이터와, 서버가 반환할 데이터를 명확히 정의.
- 데이터를 어떻게 요청하고, 어떤 형식으로 받을지를 설계합니다.
API 설계 결과물: API 명세서
API 설계의 결과는 API 명세서라는 형태로 문서화됩니다.
이 명세서는 프론트엔드 개발자와 다른 팀원들이 API를 쉽게 이해하고 활용할 수 있도록 돕는 가이드가 됩니다.
API 명세서는 마치 ERD의 API 버전과도 같습니다.
- ERD가 데이터베이스 설계의 기반이라면, API 명세서는 시스템 간 데이터 흐름과 상호작용을 정의합니다.
이번 주차 목표
이번 포스팅에서는 API 설계의 원칙과 실전 활용 방법을 배우고, 이를 바탕으로 프로젝트의 기초를 다집니다.
학습 목표
📌 1. API, HTTP 메소드 배우기
📌 2. RESTful API Endpoint 설계 배우기
📌 3. 세부적인 API 설계 배우기
🌟 1. API, HTTP 메소드 배우기
API 설계 시 필요한 것은 아래와 같습니다:
1️⃣ API Endpoint의 설계
2️⃣ 요청 데이터, 응답 데이터의 설계
위의 정보를 문서화하여 프론트엔드 개발자가 API를 사용하기 쉽게 돕는 문서를 API 명세서라고 부릅니다.
📝 API 명세서는 ERD처럼 개발 초기 단계에서 큰 틀을 설계해야 합니다.
✏️ 1-1. 용어 정리
-
💡 API (Application Programming Interface)
- 애플리케이션을 프로그래밍할 때 쉽게 작업할 수 있도록 돕는 도구 또는 인터페이스.
- 예시: 네이버 로그인 API를 사용해 간단히 로그인 기능 구현.
-
💡 REST API
- HTTP 메소드와 자원을 이용해 서로 간에 통신하는 방식.
- REST는 Representational State Transfer의 약자로, HTTP를 기반으로 한 웹 서비스 아키텍처.
-
💡 API Endpoint
- REST API에서 API 호출을 위한 HTTP 메소드와 URL의 조합.
- 예:
/users,/users/{id} - 구성 요소: HTTP 메소드 + URL = API Endpoint
-
💡 HTTP 메소드
- REST 통신 시 작업의 종류를 표시하는 방법.
- CRUD 작업에 대응하는 대표적인 5가지 메소드:
1️⃣ GET: 조회
2️⃣ POST: 생성 및 데이터 전송
3️⃣ PUT: 전체 갱신
4️⃣ PATCH: 부분 갱신
5️⃣ DELETE: 삭제
⚠️ 주의: 모든 작업을
POST로 구현 가능하나, RESTful 설계 원칙을 지키려면 적합한 메소드를 선택해야 합니다!
🌟 2. RESTful API Endpoint의 설계 규칙
RESTful의 핵심은 "리소스 중심" 설계에 있습니다.
RESTful(Representational State Transfer) 아키텍처 스타일은 HTTP 프로토콜을 기반으로 한 웹 서비스 설계 방식으로, 주로 리소스(Resource)를 중심으로 동작합니다.
즉, RESTful API는 리소스를 URI(Uniform Resource Identifier)로 표현하고, 이를 처리하기 위한 HTTP 메소드를 사용합니다.
2-1. RESTful API Endpoint 설계의 의미
API Endpoint 설계는 리소스와 작업을 조합해 사용자가 원하는 기능을 제공하는 경로(URL)를 정의하는 것을 의미합니다.
예를 들어, "게시글의 목록을 조회"하는 API가 필요하다고 가정해 봅시다.
- 리소스: 게시글(
posts) - 작업: 조회(
GET) - 엔드포인트 설계:
- GET /posts: 게시글 목록을 조회
또 다른 예: "특정 사용자의 게시글 목록을 조회"하는 API
- 리소스: 게시글(
posts), 사용자(users) - 작업: 조회(
GET) - 엔드포인트 설계:
- GET /users/{userId}/posts: 특정 사용자의 게시글 목록 조회
2-2. 설계 규칙
RESTful API의 Endpoint는 아래 규칙에 따라 설계합니다:
1️⃣ URI에 동사를 포함하지 않는다.
- ❌
/getUsers - ✅
/users - 작업은 HTTP 메소드로 표현하므로, URI에 동사를 포함할 필요가 없습니다.
2️⃣ 단어 구분은 하이픈(-)으로 한다.
- ❌
/users_list - ✅
/users-list
3️⃣ 자원(Resource)은 복수형으로 표현한다.
- ❌
/user - ✅
/users - 리소스는 여러 개의 데이터를 다룰 수 있으므로 복수형으로 설계합니다.
4️⃣ 단일 자원을 표현할 경우 식별자(id)를 추가로 사용.
- ✅
/users/{id} - 특정 데이터를 지칭할 때 고유 식별자(ID)를 URI에 포함해야 합니다.
5️⃣ 자원 간 연관 관계는 URI에 명시한다.
- ✅
/users/{id}/subjects - 계층 구조를 사용하여 자원 간 관계를 표현해야 합니다.
💡 Tip: 설계 규칙을 기본적으로 따르되, 프론트엔드 개발자가 이해하기 쉬운 API를 설계하는 것이 가장 중요합니다.
🧩 자원 간 관계 표현
-
1:1 관계:
- 특정 자원만을 명확히 표현.
- ✅
/users/{id}/subjects/{subject-id}
-
1:N 관계:
- 계층 관계에서 상위 자원이 먼저 위치.
- ✅
/users/{id}/subjects
-
N:M 관계:
- 비즈니스 로직에서 중요한 자원을 앞에 배치.
🔑 예시: 회원가입 및 로그인
-
로그인:
POST /users/login- 예시 요청:
POST https://example.com/users/login
-
회원가입:
POST /users
-
회원탈퇴 (Soft Delete):
PATCH /users
🌟 3. 세부적인 API 설계 배우기
3-1. 데이터 전달 방식
1️⃣ Path Variable
- 특정 자원을 식별할 때 사용.
- 예시:
GET /users/articles/{article-id}
2️⃣ Query String
- 검색 및 필터링 시 사용.
- 엔드포인트 뒤에
?로 시작, 여러 값은&로 연결. - 예시:
GET /users/articles?name=mango&owner=yappi
3️⃣ Request Body
- 데이터를 생성하거나 업데이트할 때 사용.
- JSON 또는 Form-data 형식으로 전송.
- 예시:
{ "name": "최용욱", "phoneNum": "010-1111-2222", "nickName": "ddol" }
4️⃣ Request Header
- 서버와 클라이언트 간의 메타데이터를 전달.
- 예시:
Authorization: Bearer <token> Content-Type: application/json
🌟 4. API 명세서 예시
- 요즘에는 노션을 사용해 작성하는 경우가 많습니다.
API 명세서 예시 스크린샷
최종적으로는, SWAGGER을 사용해서 API 명세서를 프론트엔드에게 넘겨주게 되고, 프론트엔드를 이를 확인하면서 협업하게 됩니다.
🔎 참고: HTML Form 방식의 데이터 전송
- POST 요청 시, Form 데이터를 전송하는 방식.
- 주로 회원가입, 상품 주문 등에 사용.
📤 HTTP 메시지 구조
이번 시간에는 백엔드 설계에서 매우 중요한 API 설계에 대해 배워봤습니다! 다음 포스팅에는 본격적으로 Spring Boot에 대해 배워보면서 실제로 개발을 해볼 준비를 해봅시다!😊
