API 설계 면접 질문

REST API는 Representational State Transfer의 약자로, 네트워크 기반의 분산 시스템을 구축하기 위한 아키텍처 스타일입니다. 쉽게 말해, 웹 상의 자원들을 효율적으로 주고받기 위한 규칙들의 모음이라고 생각하시면 됩니다.

RESTful API를 설계할 때 중요하게 고려해야 할 원칙들은 다음과 같습니다.

• 자원 기반 설계: 모든 것은 자원으로 표현되어야 하며, 각 자원은 고유한 URI를 통해 식별됩니다.
• HTTP 메서드 활용: GET (조회), POST (생성), PUT (수정), DELETE (삭제) 등 HTTP 메서드를 목적에 맞게 사용해야 합니다.
• 무상태성 (Stateless): 각 요청은 독립적으로 처리되어야 하며, 서버는 클라이언트의 상태를 저장하지 않아야 합니다.
• 적절한 상태 코드: 요청의 성공, 실패 여부를 명확하게 나타내는 HTTP 상태 코드를 반환해야 합니다 (예: 200 OK, 400 Bad Request, 500 Internal Server Error).

RESTful API에서 HTTP 메서드는 각각 다음과 같은 역할을 합니다.

GET은 서버에서 특정 리소스를 조회할 때 사용합니다. 예를 들어, /users/123으로 GET 요청을 보내면 ID가 123인 사용자 정보를 가져오는 것이죠.

POST는 새로운 리소스를 생성할 때 사용합니다. 예를 들어, /users로 POST 요청을 보내면서 새로운 사용자 정보를 함께 보내면, 서버는 해당 정보를 바탕으로 새로운 사용자 계정을 생성합니다.

PUT은 기존 리소스를 전체적으로 업데이트할 때 사용합니다. 예를 들어, /users/123으로 PUT 요청을 보내면서 사용자 정보 전체를 담아 보내면, ID가 123인 사용자의 정보가 완전히 새로운 정보로 대체됩니다. PUT은 멱등성을 가지기 때문에, 같은 요청을 여러 번 보내도 결과가 같습니다.

DELETE는 특정 리소스를 삭제할 때 사용합니다. 예를 들어, /users/123으로 DELETE 요청을 보내면 ID가 123인 사용자 계정이 삭제됩니다.

RESTful API 설계 시 URI는 API의 가독성과 사용성을 결정하는 중요한 요소입니다. 리소스 중심의 URI 설계를 위해 다음과 같은 원칙을 따릅니다.

첫째, URI는 리소스를 명확하게 식별해야 합니다. 따라서 동사보다는 명사를 사용하여 리소스를 표현하는 것이 좋습니다. 예를 들어, "getUsers" 보다는 "/users"가 더 적절합니다.

둘째, URI는 계층적인 구조를 가질 수 있습니다. 이는 리소스 간의 관계를 나타내는 데 유용합니다. 예를 들어, 특정 사용자의 게시물을 나타내려면 "/users/{userId}/posts"와 같이 표현할 수 있습니다.

셋째, URI는 일관성을 유지해야 합니다. API 전체에서 동일한 규칙을 적용하여 예측 가능성을 높이는 것이 중요합니다. 예를 들어, 복수형 명사를 사용하는 규칙을 정했다면 모든 리소스에 일관되게 적용해야 합니다.

이러한 원칙들을 따르면 REST 원칙을 준수하면서도 이해하기 쉽고 사용하기 편리한 API를 설계할 수 있습니다.

API 응답에서 HTTP 상태 코드는 서버가 클라이언트의 요청을 어떻게 처리했는지 알려주는 중요한 정보입니다. 클라이언트는 이 코드를 통해 요청이 성공했는지, 실패했는지, 아니면 다른 조치가 필요한지 등을 판단할 수 있습니다.

2xx 계열은 성공을 의미합니다. 예를 들어, 200 OK는 요청이 성공적으로 처리되었고, 서버가 요청한 데이터를 정상적으로 반환했다는 뜻입니다.

4xx 계열은 클라이언트 측의 오류를 나타냅니다. 400 Bad Request는 클라이언트의 요청 구문이 잘못되었거나, 서버가 이해할 수 없는 요청을 보냈을 때 발생합니다. 예를 들어, 필수 파라미터가 누락된 경우에 해당될 수 있습니다.

5xx 계열은 서버 측의 오류를 의미합니다. 500 Internal Server Error는 서버에서 예상치 못한 오류가 발생하여 요청을 처리할 수 없을 때 나타납니다. 이는 서버 코드의 버그나, 데이터베이스 연결 문제 등으로 인해 발생할 수 있습니다.

면접관님, 멱등성이란 동일한 요청을 한 번 보내든 여러 번 보내든 결과가 항상 같은 것을 의미합니다. 즉, 서버의 상태가 동일하게 유지되는 것이죠.

HTTP 메서드 중에서 멱등성이 보장되어야 하는 메서드는 주로 GET, PUT, DELETE입니다.

GET은 서버의 상태를 변경하지 않고 데이터를 조회하기 때문에 여러 번 호출해도 결과가 같습니다.

PUT은 특정 URI의 자원을 요청에 담긴 내용으로 완전히 대체합니다. 따라서 여러 번 요청해도 최종 상태는 같습니다.

DELETE는 특정 URI의 자원을 삭제합니다. 이미 삭제된 자원에 대해 DELETE 요청을 보내도 결과적으로는 자원이 없는 상태로 동일합니다.

멱등성이 중요한 이유는 네트워크 오류 등으로 인해 동일한 요청이 여러 번 전송될 수 있기 때문입니다. 멱등성이 보장되면 이러한 상황에서도 시스템의 안정성을 유지할 수 있습니다.

RESTful API에서 무상태성이란 서버가 클라이언트의 이전 요청을 기억하지 않는다는 의미입니다. 각 요청은 필요한 모든 정보를 담고 있어야 하며, 서버는 이 정보를 바탕으로 독립적으로 처리합니다.

무상태성을 유지하는 것은 API 설계 시 매우 중요합니다. 첫째, 서버의 확장성이 높아집니다. 각 서버가 독립적으로 요청을 처리할 수 있으므로, 트래픽 증가에 따라 서버를 쉽게 늘릴 수 있습니다. 둘째, 서버의 안정성이 향상됩니다. 특정 서버에 문제가 발생해도 다른 서버가 요청을 처리할 수 있어 시스템 전체의 장애를 막을 수 있습니다. 셋째, 클라이언트는 어떤 서버에 요청을 보내도 동일한 결과를 얻을 수 있어 멱등성을 보장하고, 클라이언트-서버 간의 결합도를 낮춰 독립적인 진화가 가능하게 합니다.

API 변경이 불가피할 때 버전 관리는 기존 API를 사용하던 클라이언트와의 호환성을 유지하기 위해 필수적입니다. 변경된 API로 인해 기존 클라이언트가 갑자기 작동하지 않게 되는 문제를 방지할 수 있죠.

일반적으로 많이 사용되는 버전 관리 방식으로는 URI를 이용하는 방법, 헤더를 이용하는 방법, 그리고 쿼리 파라미터를 이용하는 방법 등이 있습니다.

URI 방식은 API 엔드포인트에 버전을 명시하는 방식입니다. 예를 들어 /v1/users에서 /v2/users로 변경하는 것이죠. 헤더 방식은 HTTP 요청 헤더에 버전을 담아 전달하는 방식이고, 쿼리 파라미터 방식은 URL 쿼리 스트링에 버전을 추가하는 방식입니다. 각 방식은 장단점이 있으며, 상황에 맞춰 적절한 방법을 선택해야 합니다. API Gateway를 활용하여 버전별 라우팅을 설정하는 것도 좋은 방법입니다.

RESTful API 설계 시 자원은 명사로 표현하고 계층 구조를 반영하는 것이 좋습니다. 예를 들어, 쇼핑몰 API에서 상품 목록은 /products, 특정 상품은 /products/{product_id}와 같이 URI를 구성할 수 있습니다.

Statelessness 원칙은 각 요청이 독립적으로 처리되도록 서버에 클라이언트의 상태를 저장하지 않는 것을 의미합니다. 이를 위해 JWT(JSON Web Token)를 활용할 수 있습니다. 클라이언트가 로그인하면 서버는 JWT를 발급하고, 클라이언트는 이후 요청 시 JWT를 포함하여 인증합니다. 서버는 JWT를 검증하여 사용자를 식별하고, 별도의 세션 정보를 관리하지 않아도 됩니다. 이렇게 하면 서버의 확장성을 높이고, 클라이언트의 독립성을 보장할 수 있습니다.

API 버저닝의 주요 목적은 기존 클라이언트 애플리케이션에 영향을 주지 않으면서 API를 발전시키는 것입니다. 하위 호환성을 유지하여 클라이언트가 갑작스러운 변경으로 인해 작동을 멈추는 것을 방지합니다.

URI 버저닝은 직관적이지만 URI 구조가 복잡해지고, 캐싱이 어려워질 수 있습니다. 헤더 버저닝은 깔끔하지만, 헤더를 모르는 클라이언트는 사용하기 어렵습니다. 쿼리 파라미터 버저닝은 간단하지만, URI가 지저분해지고 가독성이 떨어집니다.

예를 들어, 모바일 앱과 같이 다양한 클라이언트가 존재하는 경우, URI 버저닝을 통해 명확하게 버전을 구분하는 것이 좋습니다. 내부 API의 경우, 헤더 버저닝을 사용하여 깔끔하게 관리할 수 있습니다. 간단한 API의 경우, 쿼리 파라미터 버저닝을 사용할 수도 있습니다. 중요한 것은 각 방식의 장단점을 이해하고 프로젝트의 특성에 맞게 선택하는 것입니다.

일관성 있는 API 에러 응답 설계는 매우 중요합니다. 클라이언트가 예상치 못한 상황에 직면했을 때, 문제의 원인을 빠르게 파악하고 적절하게 대응할 수 있도록 돕기 때문입니다.

HTTP 상태 코드는 에러의 일반적인 유형을 나타냅니다. 예를 들어, 400은 클라이언트 측의 잘못된 요청, 500은 서버 측의 오류를 의미합니다.

에러 응답 본문은 더 자세한 정보를 제공합니다. 표준화된 형식을 사용하여 오류 코드, 오류 메시지, 문제 해결에 도움이 되는 추가 정보 등을 포함하는 것이 좋습니다. 예를 들어, "invalid_parameter", "Parameter 'email' is missing"과 같은 정보를 제공하여 디버깅을 용이하게 할 수 있습니다.

이렇게 설계하면 클라이언트는 에러를 체계적으로 처리하고, 사용자에게 적절한 피드백을 제공할 수 있습니다.

대량의 데이터를 효율적으로 조회하는 API 설계 시 페이지네이션, 필터링, 정렬은 필수적입니다.

페이지네이션은 주로 Offset-Based 방식과 Cursor-Based 방식을 사용합니다. Offset-Based는 offset과 limit 파라미터를 사용하여 특정 페이지를 조회하는 방식인데, 데이터 변경이 잦을 경우 페이지가 밀리는 문제가 발생할 수 있습니다. Cursor-Based는 마지막으로 조회한 데이터의 ID 값을 기준으로 다음 데이터를 조회하는 방식이라 데이터 일관성을 유지하는 데 유리합니다.

필터링은 쿼리 파라미터를 통해 다양한 조건으로 데이터를 검색할 수 있도록 설계합니다. 예를 들어, ?status=active&category=electronics 와 같이 조건을 조합할 수 있도록 합니다.

정렬 역시 쿼리 파라미터를 활용하여 특정 필드를 기준으로 오름차순 또는 내림차순으로 정렬할 수 있도록 합니다. ?sort=name&order=asc 와 같은 방식입니다.

각 기능 설계 시에는 데이터베이스 인덱스를 적절히 활용하여 쿼리 성능을 최적화하는 것이 중요합니다. 또한, API 사용자가 쉽게 이해하고 사용할 수 있도록 명확한 API 명세와 문서화를 제공해야 합니다.

멱등성은 API 설계에서 매우 중요합니다. 왜냐하면 네트워크 불안정 등으로 인해 동일한 요청이 여러 번 전송될 수 있는데, 멱등성이 보장되면 중복 요청으로 인해 시스템 상태가 변경되는 것을 방지하고 데이터 일관성을 유지할 수 있기 때문입니다.

PUT과 DELETE는 특정 ID를 기반으로 동작하므로 기본적으로 멱등성을 가집니다. 예를 들어, PUT으로 특정 ID의 리소스를 업데이트하거나 DELETE로 특정 ID의 리소스를 삭제하는 요청은 여러 번 수행해도 결과는 같습니다.

POST는 리소스 생성을 담당하므로 멱등성을 보장하기 위해 추가적인 설계가 필요합니다. 예를 들어, 클라이언트가 요청 시 고유한 토큰을 함께 전송하고, 서버는 이 토큰을 기반으로 요청의 중복 여부를 확인하여 중복된 요청은 무시하는 방식으로 멱등성을 확보할 수 있습니다.

HATEOAS는 RESTful API 설계에서 클라이언트가 서버의 응답에 포함된 링크를 통해 다음 상태로 전이할 수 있도록 하는 원칙입니다. 즉, API 사용법을 문서가 아닌 응답 자체에서 배우도록 하는 것이죠.

장점으로는 API의 독립성이 높아져 서버 구조가 변경되어도 클라이언트가 유연하게 대응할 수 있다는 점입니다. URI가 변경되더라도 클라이언트는 응답에 포함된 링크를 따라가기만 하면 되니까요.

하지만 HATEOAS를 적용하면 응답 구조가 복잡해지고, 클라이언트 구현도 더 어려워질 수 있습니다. 또한, 초기 API 설계 단계에서 링크 관계를 충분히 고려해야 합니다.

API Gateway는 마이크로서비스 아키텍처에서 클라이언트 요청을 받아 적절한 서비스로 라우팅하는 핵심적인 역할을 합니다. 인증, 인가, 트래픽 제한, 로깅 등 공통 기능을 API Gateway에서 처리함으로써 각 마이크로서비스는 핵심 비즈니스 로직에 집중할 수 있습니다.

API 설계 원칙 준수 측면에서는 API Gateway가 일관된 API 접근점을 제공하여 클라이언트 개발 경험을 향상시키고, API 버전 관리 및 변경 사항 적용을 용이하게 합니다.

서비스 운영 효율성 측면에서는 트래픽 관리, 모니터링, 보안 정책 적용 등을 중앙 집중적으로 관리하여 운영 부담을 줄이고 전체 시스템의 안정성을 높입니다. 또한, 여러 마이크로서비스의 응답을 조합하여 클라이언트에게 최적화된 데이터를 제공하는 API 조합 기능도 제공할 수 있습니다.

분산 환경에서 API 멱등성을 보장하는 것은 매우 중요합니다. 특히 결제 시스템처럼 중요한 트랜잭션에서는 더욱 그렇습니다.

멱등성을 확보하기 위해 저는 주로 멱등성 키를 활용합니다. 클라이언트가 요청 시 고유한 키를 함께 보내면, 서버는 이 키를 기반으로 요청의 중복 여부를 판단합니다. 이미 처리된 요청이라면 동일한 응답을 반환하고, 새로운 요청이라면 처리 후 멱등성 키와 결과를 저장합니다.

결제 시스템에서는 네트워크 불안정 등으로 인해 재시도가 발생할 수 있습니다. 이 때, 멱등성 키를 사용하면 중복 결제를 방지할 수 있습니다. 또한, 분산 락을 사용하여 동시성 문제를 해결하고, 트랜잭션 실패 시 보상 트랜잭션을 통해 데이터 일관성을 유지할 수 있습니다.

잠재적인 문제점으로는 멱등성 키 관리의 복잡성, 분산 락 성능 저하 등이 있을 수 있습니다. 이를 해결하기 위해 멱등성 키 저장소를 효율적으로 관리하고, 분산 락 대신 낙관적 락을 사용하는 등의 방법을 고려할 수 있습니다.

API 버전 관리 전략은 여러 가지가 있지만, 대규모 서비스에서는 하위 호환성을 유지하면서 빠르게 변화하는 요구사항을 만족시키는 것이 중요합니다.

URI 버전 관리는 구현이 간단하지만, 캐싱 효율성이 떨어지고 API 변경 시 모든 URI를 수정해야 하는 단점이 있습니다. Content Negotiation은 클라이언트가 원하는 버전을 선택할 수 있어 유연하지만, 구현이 복잡하고 클라이언트에게 부담을 줄 수 있습니다. Query Parameter 방식은 간단하지만 URI가 지저분해지는 경향이 있습니다.

저는 점진적 배포와 API Gateway를 활용한 하이브리드 전략을 선호합니다. API Gateway에서 요청 헤더를 기반으로 버전을 라우팅하고, 새로운 기능은 점진적으로 배포하여 위험을 최소화합니다. 예를 들어, Accept 헤더를 통해 클라이언트가 특정 버전을 요청하도록 하고, API Gateway에서 해당 버전에 맞는 API로 요청을 전달하는 방식입니다. 이를 통해 클라이언트는 기존 API를 계속 사용할 수 있으며, 새로운 기능은 점진적으로 적용할 수 있습니다. 또한, API Gateway에서 요청/응답 변환을 통해 하위 호환성을 유지할 수 있습니다.

HATEOAS를 적용하면 API 변경 시 클라이언트 코드를 수정할 필요가 줄어들어 클라이언트-서버 간 결합도를 낮추고 API 탐색성을 높일 수 있습니다. 클라이언트는 서버가 제공하는 링크를 통해 다음 상태로의 전환을 스스로 결정할 수 있게 됩니다.

하지만 클라이언트 구현이 복잡해지고 서버 측 로직 또한 링크 정보를 동적으로 생성해야 하므로 복잡도가 증가할 수 있습니다. 또한, 링크 정보가 매 응답에 포함되므로 응답 크기가 커져 성능에 영향을 줄 수도 있습니다.

이러한 어려움을 극복하기 위해선, 우선 API 설계 단계에서부터 HATEOAS를 고려하여 일관성 있는 링크 구조를 설계해야 합니다. 또한, 클라이언트 라이브러리를 통해 링크 해석 및 API 호출을 자동화하고, 서버 측에서는 링크 생성을 위한 별도의 모듈을 구축하여 코드 재사용성을 높일 수 있습니다. 캐싱 전략을 적절히 활용하여 불필요한 링크 정보 생성을 줄이는 것도 중요합니다.

API Gateway와 Service Mesh를 연동하여 고급 기능을 구현하는 것은 MSA 환경에서 매우 효과적인 방법입니다. API Gateway는 외부 요청을 받아 인증/인가를 중앙 집중적으로 처리하고, Service Mesh는 서비스 간 통신을 안전하고 효율적으로 관리합니다.

예를 들어, API Gateway에서 JWT 토큰 기반 인증을 수행하고, Service Mesh는 mTLS를 통해 서비스 간 상호 인증을 강화할 수 있습니다. 또한, API Gateway에서 요청/응답 데이터 변환을 수행하여 클라이언트와 서비스 간 호환성을 높이고, Service Mesh는 트래픽을 분산하고 서킷 브레이커를 적용하여 안정성을 확보할 수 있습니다.

이러한 연동을 통해 보안, 트래픽 관리, 데이터 처리 등 다양한 측면에서 MSA 시스템의 효율성과 안정성을 크게 향상시킬 수 있습니다. 서비스 디스커버리 연동을 통해 서비스 위치 변경에 유연하게 대응하는 것도 중요한 장점입니다.

하이브리드 아키텍처 설계 시 동기/비동기 API의 목적을 명확히 구분하는 것이 중요합니다. 사용자에게 즉각적인 응답이 필요한 작업은 동기 REST API로, 시간이 걸리거나 백그라운드 처리가 가능한 작업은 비동기 이벤트 기반 API로 처리하는 것이 좋습니다.

일관성 모델은 최종 일관성을 고려해야 하며, 데이터 정합성을 위해 멱등성을 보장해야 합니다. 메시지 큐를 사용하여 이벤트 전달을 안정적으로 관리하고, 데드 레터 큐를 통해 실패한 메시지를 격리하여 재처리하거나 분석할 수 있습니다.

오류 처리는 API Gateway에서 공통적으로 처리하고, 분산 트랜잭션 관리를 통해 데이터 불일치를 최소화해야 합니다. 모니터링은 분산 트레이싱 도구를 활용하여 API 호출 흐름을 추적하고, 로그 수집 및 분석을 통해 시스템 상태를 지속적으로 관찰해야 합니다. 각 API의 성능 지표를 수집하고 시각화하여 이상 징후를 빠르게 감지하는 것이 중요합니다.

API Rate Limiting 알고리즘 선택은 시스템 요구사항에 따라 달라집니다. 토큰 버킷은 구현이 간단하고 버스트 트래픽을 처리하기 용이하지만, 리키 버킷은 트래픽을 더 균일하게 조절합니다. 고정 윈도우는 단순하지만 윈도우 경계에서 트래픽이 몰릴 수 있고, 슬라이딩 윈도우는 더 정확하지만 계산 복잡도가 높습니다.

분산 환경에서는 Redis와 같은 중앙 집중식 저장소를 사용하여 Rate Limit 정보를 공유해야 합니다. 클라이언트별/엔드포인트별 정책을 적용하려면 각 키에 대한 Rate Limit 설정을 저장하고 관리해야 합니다.

버스트 트래픽을 허용하면서 시스템 안정성을 유지하기 위해선, 토큰 버킷과 함께 Circuit Breaker 패턴을 적용할 수 있습니다. 특정 사용자의 요청이 실패율을 넘어서면 Circuit Breaker가 작동하여 시스템 과부하를 방지합니다. 또한, 우선순위 큐를 사용하여 중요한 요청을 먼저 처리하는 것도 좋은 방법입니다.

GraphQL을 대규모 서비스에 도입하면 REST API 대비 몇 가지 뚜렷한 이점을 얻을 수 있습니다. 가장 큰 장점은 클라이언트가 필요한 데이터만 정확하게 요청하여 Over-fetching과 Under-fetching 문제를 해결할 수 있다는 점입니다. 또한, 스키마 기반으로 타입 안정성을 확보하고, 단일 엔드포인트를 통해 API 관리를 단순화할 수 있습니다.

하지만 새로운 아키텍처적 도전 과제도 발생합니다. 예를 들어, N+1 문제는 DataLoader 패턴을 사용하여 해결할 수 있습니다. 캐싱은 클라이언트, CDN, 서버 레벨에서 복잡한 전략이 필요하며, API Gateway 레벨에서 GraphQL을 적용하여 보안 및 모니터링을 강화할 수 있습니다. 스키마 설계 단계에서부터 성능과 보안을 고려하는 것이 중요하며, Resolver 최적화를 통해 쿼리 성능을 향상시킬 수 있습니다.