원문 : [MEDIUM] API Design 101: From Basics to Best Practices
API 디자인 기본부터 최고의 사례까지
- API 디자인 개요: API 디자인은 입력(예: 새 상품에 대한 상품 세부 정보)과 출력(예: 상품 조회 시 반환되는 정보)을 정의하는 것에 초점을 맞춥니다. 이는 인터페이스에 집중함을 의미하며, 낮은 수준의 구현보다는 상호작용 방식을 중시합니다.
- CRUD 작업: 생성(Create), 읽기(Read), 업데이트(Update), 삭제(Delete)는 데이터 기반 애플리케이션의 기본 작업입니다. 이 작업들은 사용자나 시스템이 e-commerce API와 상호작용하는 방식을 정의하는 데 중요합니다.
- 통신 프로토콜 및 데이터 전송 메커니즘: HTTP, WebSockets 등의 통신 프로토콜과 JSON, XML, 프로토콜 버퍼 같은 데이터 전송 메커니즘을 결정하는 것이 포함됩니다.
- API 패러다임: REST, GraphQL, gRPC와 같은 다양한 API 패러다임이 있으며, 각각 고유한 프로토콜과 표준을 가지고 있습니다.
- API 디자인에서의 관계: e-commerce 설정에서 사용자와 주문, 주문과 제품 등과 같은 관계를 가질 수 있으며, 이러한 관계를 반영하여 엔드포인트를 디자인하는 것이 중요합니다.
- 쿼리, 제한 및 GET 요청의 멱등성: GET 요청은 데이터를 변경하지 않고 검색만을 목적으로 해야 하며, 여러 번 호출해도 결과가 변경되지 않는 멱등성을 가져야 합니다.
- 역호환성 및 버전 관리: 엔드포인트를 수정할 때 기존 클라이언트를 깨뜨리지 않도록 역호환성을 유지하는 것이 중요합니다. 버전 관리를 통해 주요 변경 사항을 처리하는 것이 일반적인 방법입니다.
- 속도 제한 및 CORS: 사용자가 특정 시간 동안 요청할 수 있는 수를 제어하기 위해 속도 제한을 설정하는 것이 중요합니다. 또한, 웹 보안을 위해 CORS 설정을 설정하는 것이 일반적입니다.
핵심 요약
- API 디자인은 인터페이스에 초점을 맞추며 CRUD 작업을 통해 사용자와 시스템의 상호작용을 정의합니다.
- 다양한 API 패러다임(REST, GraphQL, gRPC)은 각각의 장단점과 특성을 가지며, 통신 프로토콜과 데이터 전송 메커니즘을 선택하는 것이 포함됩니다.
- API의 역호환성과 버전 관리는 기존 클라이언트를 보호하며, 속도 제한 및 CORS 설정은 API의 안정성과 보안을 유지하는 데 중요합니다.
용어 정리
- CRUD: 생성(Create), 읽기(Read), 업데이트(Update), 삭제(Delete)를 의미하는 데이터 기반 애플리케이션의 기본 작업입니다.
- 멱등성(Idempotence): 동일한 연산을 여러 번 적용해도 결과가 달라지지 않는 성질을 말합니다. GET 요청은 멱등해야 합니다.
- 역호환성(Backward Compatibility): 새로운 버전의 API가 이전 버전과 호환되어 기존 클라이언트가 여전히 작동할 수 있도록 하는 성질입니다.
- CORS (Cross-Origin Resource Sharing): 웹 페이지가 다른 도메인의 리소스에 접근할 수 있도록 허용하는 메커니즘으로, 웹 보안의 중요한 부분입니다.
