API란?
REST API 설계 원칙과 응답 구조

프로그램이 데이터와 기능을 예측 가능하게 주고받을 계약을 만듭니다.

API 설계은 무엇인가요?

API는 서로 다른 프로그램이 기능과 데이터를 주고받기 위해 합의한 인터페이스입니다. 웹 API에서는 URL, 메서드, 입력과 응답 형식이 하나의 계약이 됩니다.

좋은 API는 정상 응답만 짧게 만드는 것이 아니라 오류, 권한, 재시도와 변경 가능성을 예측 가능하게 설계합니다.

도구 이름보다 각 요소가 맡는 책임과 서로 연결되는 방식을 먼저 이해하는 것이 좋습니다.

URL은 행동보다 사용자, 주문, 게시물처럼 다루는 대상을 중심으로 표현합니다.

GET, POST, PUT, PATCH, DELETE와 상태 코드의 의미를 일관되게 사용합니다.

코드, 사용자 메시지, 개발용 세부 정보와 추적 ID를 구분합니다.

필드 추가와 폐기, 버전 전환이 기존 클라이언트를 깨뜨리지 않게 합니다.

한 제품을 완성할 때는 한 가지 도구가 아니라 역할이 다른 여러 기술을 조합합니다.

HTTP 리소스와 메서드를 중심으로 한 범용 방식

클라이언트가 필요한 데이터 형태를 질의

gRPC·tRPC처럼 함수 호출과 타입 계약 중심

OpenAPI·JSON Schema·Contract tests

REST와 REST API는 같은 말인가요?

REST는 아키텍처 제약을 뜻하고 REST API는 이를 웹 API에 적용한 표현입니다. 실제 서비스는 요구에 맞게 일부 원칙을 선택해 사용하기도 합니다.

GraphQL이 REST보다 항상 좋은가요?

아닙니다. 복잡한 데이터 조합에는 유용하지만 캐시, 권한, 쿼리 비용과 운영 복잡성을 함께 감당해야 합니다.