The API Testing Checklist I Use for Every Endpoint

3년 전, 저는 오전 2시에 생산 API가 "32/13/2021"이라는 형식으로 날짜 필드를 보낼 때 발생하는 상황을 아무도 테스트하지 않아서 화려하게 실패하는 것을 보았습니다. 그 결과는 최악의 방식으로 아름다웠습니다: 47,000개의 실패한 거래, 지원 채널에 몰려드는 화난 고객들, 그리고 제가 대답할 수 없는 솔루션을 요구하는 CEO. 그날 밤은 API 테스트를 접근하는 방식을 영원히 바꾸었습니다.

저는 사라 첸이며, QA 자동화 엔지니어로 8년을 일해왔고, 지난 5년은 핀테크 및 의료 플랫폼의 API 테스트에 전념했습니다. 저는 간단한 CRUD 엔드포인트부터 매일 수백만 달러를 처리하는 복잡한 결제 처리 API에 이르기까지 모든 것을 테스트했습니다. 제가 배운 것은 이렇습니다: 대부분의 API 실패는 이국적인 엣지 케이스가 아니라 체계적 체크리스트로 잡을 수 있는 예측 가능한 문제들입니다.

오늘 공유하는 체크리스트는 제가 테스트하는 모든 엔드포인트에서 사용하는 정확한 것입니다. 이 체크리스트 덕분에 지난 1년 동안 저희 팀은 적어도 12건의 생산 사고를 막을 수 있었고, 주니어 엔지니어들도 따를 수 있을 만큼 포괄적이면서도 시니어 개발자들이 놓치는 문제를 잡아낼 만큼 상세합니다. 이것은 이론이 아닙니다—수백 개의 API 구현을 통해 정제된 전투 테스트된 프로세스입니다.

인증 및 권한 부여: 기초 레이어

저는 다른 것을 테스트하기 전에 보안 경계를 검증합니다. 이는 단순히 인증이 작동하는지 확인하는 것이 아니라, 모든 인증 시나리오와 권한 경계를 체계적으로 탐색하는 것입니다. 저는 유효한 자격 증명으로는 완벽하게 작동하지만 자격 증명이 누락되거나 잘못되었거나 잘못된 사용자에게 속할 때 재앙적으로 실패하거나 데이터를 유출하는 API를 너무 많이 보았습니다.

우선, 아무 인증 토큰 없이 테스트합니다. 해당 엔드포인트는 401 Unauthorized 상태를 반환해야 하며, 절대 500 Internal Server Error를 반환하거나 실제 데이터를 반환해서는 안 됩니다. 저는 인증 토큰 없이 제공했을 때 전체 사용자 기록을 반환한 생산 API를 만난 적이 있습니다. 왜냐하면 개발자가 인증 미들웨어가 항상 실행될 것이라고 가정했기 때문입니다. 하지만 그렇지 않았습니다.

다음으로 만료된 토큰으로 테스트합니다. 이것은 놀라운 수의 문제를 잡아냅니다. 왜냐하면 토큰 만료 로직은 초기 인증과는 코드베이스의 다른 부분에 있는 경우가 많기 때문입니다. 응답은 토큰이 만료되었다는 메시지와 함께 명확한 401이어야 하며, "unauthorized"라는 일반적인 메시지로 클라이언트가 새로 고칠지 재인증할지 추측하게 해서는 안 됩니다.

그런 다음 잘못된 형식의 토큰—임의의 문자열, 제거된 문자가 포함된 토큰, 다른 시스템의 토큰으로 테스트합니다. API는 스택 트레이스나 내부 오류 세부정보를 노출하지 않고 이를 우아하게 처리해야 합니다. 유니코드 문자가 포함된 토큰을 주었을 때 전체 서비스를 중단시킨 API를 한 번 발견한 적이 있습니다. JWT 파싱 라이브러리가 인코딩을 적절하게 처리하지 않았기 때문입니다.

권한 테스트는 흥미로운 부분입니다. 저는 자원에 접근할 수 없어야 하는 사용자의 유효한 토큰으로 테스트합니다. GET /users/123 엔드포인트의 경우, 저는 사용자 456으로 인증하고 123의 데이터에 접근하려고 시도합니다. 응답은 403 Forbidden이어야 하며, 404 Not Found (리소스 존재에 대한 정보를 유출) 또는 데이터를 포함한 200이어서는 안 됩니다.

또한 체계적으로 역할 기반 접근 제어를 테스트합니다. API에 관리, 관리자의 역할, 일반 사용자 역할이 있다면, 각 역할로 각 엔드포인트를 테스트합니다. 저는 매트릭스 스프레드시트를 유지합니다: 행은 엔드포인트, 열은 역할, 셀에는 예상 상태 코드가 포함됩니다. 이것은 허가 오류를 생산에 도달하기 전에 잡아내어 보안 취약점이 되는 것을 방지합니다.

요청 검증: 입력 경계 테스트

입력 검증은 대부분의 API가 실제 품질을 보여주는 곳입니다. 잘 설계된 API는 모든 입력 필드를 철저히 검증하고 명확하고 실행 가능한 오류 메시지를 반환합니다. 잘못 설계된 API는 쓰레기 데이터를 수용하거나 신비스럽게 중단됩니다.

"대부분의 API 실패는 이국적인 엣지 케이스가 아니라 체계적 체크리스트로 잡을 수 있는 예측 가능한 문제입니다."

필수 필드 테스트로 시작합니다. 모든 필수 필드에 대해, 그 필드 없이 요청을 보냅니다. API는 어떤 필드가 누락되었는지를 명확히 식별하는 메시지와 함께 400 Bad Request를 반환해야 합니다. "검증 오류"라는 메시지만 반환하여 무엇이 실패했는지 명시하지 않는 API를 보았습니다. 이로 인해 개발자는 문제가 발생한 15개 필드 중 어느 것이 문제인지 추측해야 했습니다.

그런 다음 데이터 유형 검증을 테스트합니다. 필드가 정수를 기대하는 경우, 문자열, 부동 소수점, 불린, null, 배열 및 객체를 보냅니다. 각각은 "age must be an integer"와 같은 명확한 메시지와 함께 400을 반환해야 하며, "invalid request format"은 안 됩니다. 한 번은 수량에 대한 문자열을 보내는 것이 0개의 항목에 대한 주문을 생성하여 전체 이행 파이프라인을 깨뜨린 전자상거래 API를 테스트했습니다.

문자열 길이 검증은 중요하며 종종 간과됩니다. 빈 문자열, 단일 문자, 최대 길이의 문자열, 최대 길이를 초과한 문자열 및 비정상적으로 긴 문자열(10,000자 이상)로 테스트합니다. 잘못 검증된 필드에 메가바이트 크기의 문자열을 보내 메모리 소진을 초래하여 생산 데이터베이스를 중단시킨 적이 있습니다.

숫자 필드의 경우, 경계 값을 체계적으로 테스트합니다: 0, 음수, 정수가 기대될 때의 소수, 최대 정수 값을 초과하는 숫자, 그리고 무한대 또는 NaN과 같은 특수 값. 제가 테스트한 결제 API는 한 번 음수 결제 금액을 수용하여 사용자가 자유롭게 계좌에 적립할 수 있게 했습니다.

날짜 및 시간 검증은 특별한 주의를 기울여야 합니다. 일관되게 문제가 발생하기 때문입니다. 잘못된 날짜(2월 30일, 13월), 다양한 형식(ISO 8601, 유닉스 타임스탬프, 인간이 읽을 수 있는 문자열), 과거 또는 미래의 날짜 및 시간대 엣지 케이스로 테스트합니다. 시작 부분에서 언급한 오전 2시 사고는 날짜 검증 실패였습니다.

enum 필드의 경우, 유효한 값, 잘못된 값, 대소문자 변형 및 null로 테스트합니다. API가 "active" 및 "inactive"를 상태 값으로 수용한다면, "ACTIVE", "Active", "pending", 빈 문자열 및 null로 시도합니다. 각각은 수용되거나 (대소문자 구분이 없는 경우) 유효한 옵션을 나열하는 명확한 메시지와 함께 거부되어야 합니다.

응답 검증: 데이터 무결성 보장

무엇이 들어가는지 테스트하는 것만큼 무엇이 돌아오는지를 테스트하는 것도 중요합니다. 요청을 완벽하게 수용하지만 클라이언트 애플리케이션을 깨뜨리는 불일치하거나 불완전하거나 잘못 포맷된 데이터를 반환하는 API를 보았습니다.