📚[Backend Development] API 명세서 작성을 뒷받침하는 핵심적인 개념들

✅ 1. API 명세서 작성 시 사용자의 편의성을 만족하게 작성해야 하는 이유.

API의 ‘사용자’는 일반 고객이 아니라, 이 API를 호출하여 개발하는 다른 개발자(프론트엔드, 모바일 앱 등)입니다.
이들의 편의성을 만족시켜야 하는 이유는 개발 전체의 생산성과 안정성을 높이기 위함입니다.

• 생산성 향상 : API가 직관적이고 사용하기 편리하면, 클라이언트 개발자는 불필요한 질문이나 추측 없이 빠르게 기능을 구현할 수 있습니다. 이는 전체 프로젝트의 개발 속도를 높입니다.
• 오류 감소 : API의 동작 방식이 예측 가능하고 일관되면(예: 검색 결과는 항상 배열), 클라이언트 개발자가 실수할 가능성이 줄어들어 버그 발생률이 낮아집니다.
• 쉬운 유지보수 : 잘 설계된 API는 나중에 기능을 수정하거나 확장할 때도 이해하기 쉬워 유지보수가 용이합니다.

결론 : 동료 개발자를 위한 ‘좋은 도구’를 만든다고 생각하시면 됩니다. 좋은 도구는 사용하기 편하고, 실수를 줄여주며, 결과적으로 더 나은 결과물을 더 빨리 만들게 해줍니다.

✅ 2. 데이터의 정합성이란 무엇인가요?

데이터의 정합성(Data Integrity) 이란, 데이터가 특정 조건이나 규칙을 항상 만족하여 모순 없이 정확하고 일관된 상태를 유지하는 것을 의미합니다.

• 예시 1: ‘재고’ 데이터는 음수(-)가 될 수 없다는 규칙을 항상 지켜야 합니다.
• 예시 2: ‘주문’내역에 있는 productId는 반드시 ‘상품’테이블에 실제로 존재하는 ID여야 합니다.
• 예시 3: 이익률(margin)은 항상 실제 가격 데이터에 기반한 계산 결과와 일치해야 합니다.

결론 : 데이터베이스 속 데이터들이 서로 충돌하거나 논리적으로 말이 안 되는 상황 없이, 언제나 ‘올바른’ 상태로 존재하는 것을 의미합니다.

✅ 3. API 명세서 작성 시 데이터의 정합성을 만족하게 작성해야 하는 이유.

API는 데이터베이스의 ‘문지기’ 역할을 하기 때문입니다.
API의 설계는 데이터의 정합성을 지키거나 깨뜨리는 데 결정적인 영향을 미칩니다.

• 잘못된 데이터 방지 : API는 요청 데이터를 검증하여, 정합성을 해치는 데이터(예: 재고를 음수로 만들려는 요청)가 데이터베이스에 저장되지 않도록 막아야 합니다.
• 트랜잭션 보장 : ‘상품 등록과 초기 재고 입력’처럼 여러 작업을 하나로 묶어, 모두 성공하거나 모두 실패하게 만들어 데이터가 모순된 상태로 남지 않도록 보장해야 합니다.
• 계산된 값 보호 : margin이나 totalStockCount처럼 계산되는 값을 클라이언트가 직접 수정할 수 없도록 API를 설계해야 합니다. 오직 원본 데이터(가격, 재고량 등)만 수정 가능하게 하여 정합성을 유지합니다.

결론: API는 데이터 정합성을 지키기 위한 규칙을 강제하는 최전성입니다. API 설계가 허술하면, 시스템 전체의 데이터가 망가질 수 있습니다.

✅ 4. RESTful 디자인 원칙이란 무엇인가요?

RESTful 디자인 원칙은 웹 서비스를 만들기 위한 일종의 ‘모범 설계 양식’ 또는 ‘가이드라인’입니다.
이 원칙을 따르면 누구나 이해하기 쉽고, 확장하기 편하며, 일관된 API를 만들 수 있습니다.
핵심적인 원칙은 다음과 같습니다.

1. 자원(Resource) : 모든 데이터는 상품, 주문과 같은 ‘자원’으로 표현되며, 각 자원은 고유한 URL 주소를 가집니다.(예: /products, /products/123)
2. 행위(Verd) : 자원에 대한 행위는 HTTP Method(GET, POST, PUT, PATCH, DELETE)로 표현합니다.(예: GET /products - 상품 조회)
3. 표현(Representation) : 자원의 상태는 JSON이나 XML 같은 형태로 주고받습니다.

결론 : ‘URL로는 대상을 표현하고, HTTP Method로는 행위를 표현하자’ 는 것이 RESTful 디자인의 가장 기본적인 철학입니다.

✅ 5. API 명세서 작성 시 RESTful 디자인 원칙을 만족하게 작성해야 하는 이유.

RESTful 디자인 원칙은 전 세계 개발자들 사이의 ‘공통 언어’ 또는 ‘문법’ 과 같기 때문입니다.

• 예측 가능성 : GET /products/1 이라는 URL만 봐도, 개발자 누구나 ‘1번 상품의 정보를 조회하는구나’라고 쉽게 예측할 수 있습니다. 이는 API를 배우고 사용하는 시간을 크게 단축시킵니다.
• 플랫폼 독립성 : 웹, 모바일 앱, 다른 서버 등 HTTP 통신만 가능하다면 어떤 클라이언트든 동일한 방식으로 API를 사용할 수 있습니다.
• 확장성 : 명확한 규칙과 구조를 가지므로, 나중에 새로운 기능을 추가하거나 시스템을 확장할 때 더 수월합니다.
• 일관성 : 프로젝트 내 모든 API가 동일한 규칙을 따르므로, 전체적인 코드의 품질과 유지보수성이 향상됩니다.

결론 : 우리가 맞춤법과 문법에 맞춰 글을 쓰는 것처럼, API도 RESTful이라는 ‘문법’에 맞춰 작성해야 다른 개발자들이 쉽게 이해하고 협업할 수 있습니다.