API Gateway를 사용하여 API 변경으로 인한 문제를 방지하는 방법
September 11, 2023
API를 개발할 때, 현재 API 사용자에게 문제를 일으킬 수 있는 변경 사항을 가끔 적용하게 됩니다. API를 진화시키는 것은 현재 사용자에게 영향을 미치지 않으면서 제품을 발전시키는 데 필수적입니다. 그렇지 않으면 사용자들이 제공하는 서비스에 대한 신뢰를 잃을 수 있습니다. 이러한 문제를 완전히 피하는 것은 불가능하지만, 영향을 최소화하거나 주요 변경 사항을 사전에 파악할 수 있습니다. 주요 변경 사항은 개발 단계에서 식별되어야 하며, 발생할 경우 API 게이트웨이가 이를 처리하여 클라이언트 애플리케이션이 영향을 받지 않도록 해야 합니다. 이 글에서는 APISIX API 게이트웨이를 사용하여 API 주요 변경 사항을 방지하고 처리하는 몇 가지 모범 사례와 전략을 탐구해 보겠습니다.
API 주요 변경 사항이란 무엇인가요?
소프트웨어 제품은 지속적으로 진화하며, 그들의 API도 예외는 아닙니다. 이러한 API는 외부 API 소비자가 시스템과 상호 작용하는 주요 인터페이스 역할을 하며, 제품의 변화를 반영합니다. 이러한 API 변경은 기술적 개선, 비즈니스 방향 전환, 중요한 버그 수정 등 다양한 이유로 발생합니다. 간단히 말해, 주요 변경 사항은 API를 변경했을 때 이를 사용하는 클라이언트 애플리케이션에 문제를 일으킬 수 있는 경우를 말합니다. 이러한 변경 사항 중 일부는 다른 것들보다 쉽게 발견될 수 있습니다. 다음은 주요 변경 사항의 몇 가지 예입니다:
- 엔드포인트 제거:
GET /users엔드포인트가 있고 이를 제거하기로 결정했다면, 이를 접근하려는 클라이언트는 오류를 받게 됩니다. - 엔드포인트 URL 변경: 엔드포인트 URL을
GET /users에서GET /members로 변경하면, 이전 URL을 사용하는 클라이언트는 문제를 겪게 됩니다. - 요청 페이로드 수정: 엔드포인트가 요청에서 특정 데이터를 기대하는 경우, 예를 들어
POST /users가{ "name": "John" }을 기대하지만 이를{ "firstName": "John" }으로 변경하면, 이전 형식을 보내는 클라이언트는 중단됩니다. - 응답에서 필드 제거 또는 이름 변경: 클라이언트가 API 응답에서 특정 필드를 기대하는 경우, 이를 제거하거나 이름을 변경하면 해당 클라이언트가 오작동할 수 있습니다. 예를 들어,
{ "id": 1, "name": "John" }을{ "id": 1, "fullName": "John Doe" }로 변경하는 경우입니다. - 데이터 타입 변경: API 필드가 문자열로 기대되지만 이를 정수나 다른 타입으로 변경하면 클라이언트가 중단될 수 있습니다. 예를 들어,
"age": "25"를"age": 25로 변경하는 경우입니다. - 인증 메커니즘 변경: 기본 인증에서 토큰 기반 인증으로 전환할 때 적절한 전환 절차 없이 진행하면 기존 클라이언트는 인증 오류를 겪게 됩니다.
- 필수 필드 도입:
POST /users와 같은 엔드포인트가 선택적 필드를 받다가 갑자기 필수 필드를 도입하면, 해당 필드를 보내지 않는 기존 클라이언트는 문제를 겪게 됩니다. - 오류 형식 변경: 클라이언트가 특정 오류 형식을 이해하도록 프로그래밍된 경우, 이러한 형식을 변경하면 클라이언트 측에서 적절하지 않은 오류 처리가 발생할 수 있습니다.
- HTTP 상태 코드 수정: 특정 작업에 대한 상태 코드를 변경하는 경우, 예를 들어 리소스 생성에 대해
201 Created대신200 OK를 반환하면 클라이언트를 오도할 수 있습니다. - 이전 API 버전 지원 중단: 적절한 전환 기간 없이 이전 버전 지원을 단계적으로 중단하면, 해당 버전에 의존하는 클라이언트는 중단됩니다.
API의 모든 변경 사항은 클라이언트 애플리케이션을 중단시킬 가능성이 있습니다. 백엔드 API의 정문 역할을 하는 API 게이트웨이를 사용하면, 게이트웨이는 라우트 구성에 정의된 규칙 집합을 기반으로 요청을 어디로 전달할지 알고 있으며, API 주요 변경 사항을 처리하기에 적합한 위치입니다. APISIX를 사용하여 일부 API 변경 사항을 식별하는 방법을 살펴보겠습니다.
요청 및 응답 스키마 검증
라우트에 대한 엄격한 스키마를 정의하면 요청 및 응답 구조가 예상대로인지 확인할 수 있습니다. request-validation 플러그인을 사용하여 들어오는 요청을 검증하고, response-rewrite 플러그인을 사용하여 특정 조건에 따라 API 응답을 재작성할 수 있습니다.
로깅
APISIX는 http-logger, elasticsearch-logger, file-logger 등 다양한 로깅 플러그인을 지원합니다. 로거를 설정하여 API 요청 및 응답 데이터를 저장하고, 로그를 정기적으로 분석하여 요청/응답 헤더, 페이로드 구조 또는 기타 비정상적인 패턴의 변화를 감지할 수 있습니다.
라우트 및 업스트림 모니터링
게이트웨이를 통과하는 라우트를 모니터링하세요. 이전에 사용 가능했던 라우트가 갑자기 404 오류를 반환하기 시작하면, API가 변경되었거나 엔드포인트가 중단되었을 가능성이 있습니다. API 상태 확인 기능을 활성화하여 업스트림 노드의 전반적인 상태를 지속적으로 모니터링하세요. 노드 중 하나가 실패하거나 평소보다 빠르거나 느리게 응답하기 시작하면, 이는 기본 백엔드 서비스의 처리에 변화가 있음을 나타낼 수 있습니다. Prometheus와 같은 모니터링 도구를 prometheus 플러그인을 사용하여 APISIX와 통합하세요. 4xx 또는 5xx 오류 비율 증가와 같은 메트릭을 기반으로 경고를 설정하여 API의 주요 변경 사항을 나타낼 수 있습니다.
버전 관리 사용
API 버전 관리는 API의 변경 사항을 관리하고 이러한 변경 사항이 API 소비자 앱에 방해가 되지 않도록 하는 방법입니다. APISIX와 함께 버전 관리를 설정하는 다양한 방법이 있으며, URI 경로, 쿼리 매개변수, 헤더 또는 콘텐츠 유형을 선택하는 방법이 있습니다. 예를 들어, /v1/users 또는 /v2/users와 같은 웹 주소를 사용하여 API의 버전을 표시할 수 있습니다. 이러한 버전을 통해 API의 여러 옵션을 제공할 수 있으며, API 소비자가 자신의 속도에 맞춰 최신 버전으로 업그레이드할 시기를 결정할 수 있습니다. APISIX는 새로운 버전의 문제를 해결할 때까지 모든 트래픽을 이전의 안정적인 버전의 API로 다시 리디렉션할 수 있어 API를 하위 호환성 있게 만듭니다. 새로운 버전에서 문제를 감지하면 traffic-split 플러그인을 사용하여 빠르게 롤백할 수 있습니다.
중단 예고
기능을 제거하거나 변경하기 전에 이를 중단 예고로 표시하여 소비자가 적응할 시간을 충분히 제공하세요. APISIX의 도움으로 라우트를 구성하여 향후 중단 및 대체에 대해 알릴 수 있습니다. 이를 위해 APISIX는 response-rewrite를 제공합니다.
버전 관리와의 통합
풀 리퀘스트 리뷰어가 주요 변경 사항을 발견하기를 바랄 수 있지만, 이 방법에만 의존하는 것은 확실하지 않으며 결국 실패로 이어질 수 있습니다. API에 대한 OpenAPI/Swagger 문서가 있다면, 이를 버전 관리하고 CI 파이프라인에 포함시킬 수 있습니다. APISIX는 Git과 같은 버전 관리 시스템과의 직접적인 통합을 기본적으로 지원하지 않습니다. 그러나 APISIX 외부에서 프로세스를 설정할 수 있습니다. Oasdiff 또는 Bump와 같은 도구는 API 사양의 변경 사항을 식별하고, APISIX의 라우트 엔드포인트에 대해 테스트를 실행하는 CI 파이프라인을 트리거하여 주요 변경 사항이 도입되지 않았는지 확인할 수 있습니다.
변경 사항을 감지하는 다른 방법
Postman에는 현재 API 버전의 주요 변경 사항을 자동으로 확인하는 템플릿이 있으며, 이 글에서 작동 방식에 대해 설명합니다. 이 감지기를 CI 파이프라인에 추가 단계로 추가할 수 있습니다. 파이프라인이 실행될 때마다 주요 변경 사항 감지기는 현재 API 사양을 이전 사양과 비교하여 차이점을 알려줍니다. 개발 스택에 따라 OpenAPI 사양을 비교하는 다른 라이브러리가 있습니다. 이 글은 새로운 변경 사항을 프로덕션에 적용하기 전에 테스트된 배포 전략을 사용하여 실제로 이를 잡아내는 방법을 잘 설명합니다.
요약
API 주요 변경 사항을 감지하고 방지하는 것은 API 소비자와의 신뢰를 유지하고 서비스의 성공을 보장하는 데 중요합니다. APISIX의 요청 검증, 버전 관리, 로깅, 모니터링 및 경고 기능을 자동화된 API 계약 테스트와 같은 기술과 통합함으로써, 클라이언트에게 부정적인 영향을 미치지 않으면서 API를 진화시킬 수 있습니다.