이 문서에서는 효율적인 API 설계, 테스트 및 협업을 위해 설계된 API-first 도구인 Apidog의 핵심 개념을 소개합니다. 많은 개념이 Postman과 같은 유사 제품과 다릅니다. 이러한 개념을 이해하면 Apidog의 워크플로를 효과적으로 탐색하는 데 도움이 됩니다.프로젝트#
Apidog의 프로젝트(Project) 는 협업의 기본 단위이며, 모듈, 환경, 테스트 시나리오 등을 포함합니다. 이는 팀 내 모든 API 관련 작업을 담는 컨테이너 역할을 합니다.프로젝트의 주요 구성 요소#
모듈: 엔드포인트 및 관련 구성 요소의 논리적 그룹입니다.
환경: 다양한 배포 단계(예: 개발, 스테이징, 프로덕션)를 위한 변수 집합입니다.
테스트 시나리오: 자동화 테스트를 위한 요청 모음입니다.
엔드포인트 사양: OpenAPI/Swagger 표준을 기반으로 한 API 문서입니다.
Postman과의 비교#
| Apidog 개념 | Postman의 해당 개념 | 설명 |
|---|
| 프로젝트 | 워크스페이스 | 협업을 위한 최상위 조직 단위입니다. |
| 모듈 | 컬렉션 폴더 | 관련 엔드포인트를 그룹화합니다. |
| 팀 | 팀 | 공유 액세스 및 협업 기능입니다. |
프로젝트를 사용하면 여러 사용자가 버전 관리 및 액세스 권한을 유지하면서 동시에 API 작업을 수행할 수 있어 원활한 협업이 가능합니다.
모듈의 기능#
관련 엔드포인트, 스키마, 응답 및 보안 스킴을 포함합니다.
자동 URL 생성을 위해 환경별 Base URL 로 구성됩니다.
표준 준수를 개선하기 위해 모듈 수준의 가져오기/내보내기 작업을 지원합니다.
모듈 사용 시점#
마이크로서비스의 경우: 각 서비스를 별도의 모듈로 사용합니다.
여러 API의 경우: 기능 또는 도메인별로 엔드포인트를 그룹화합니다.
기본값: 새 프로젝트는 하나의 모듈로 시작하며, 여러 Base URL이 필요한 경우 필요에 따라 더 추가합니다.
모듈은 OpenAPI Specification(OAS)과 일치하므로 다른 도구와의 통합을 촉진하고 깔끔한 API 경계를 유지하는 데 도움이 됩니다.
엔드포인트#
엔드포인트(Endpoint) 는 Apidog의 API-first 접근 방식에서 핵심 요소이며, 특정 API 작업(예: GET /users/{id})을 나타냅니다.엔드포인트 관리#
저장된 요청 예시를 위해 엔드포인트 케이스와 연결됩니다.
Postman과의 차이점#
| 측면 | Apidog(엔드포인트 기반) | Postman(요청 기반) |
|---|
| 기본 단위 | 엔드포인트(API 사양) | 요청(개별 호출) |
| 사양 변경 | 케이스 및 테스트가 자동 업데이트됨 | 수동 재작성이 필요함 |
| 구조 | 디버깅이 포함된 OAS 확장 | 사양과 요청이 분리됨 |
Apidog에서는 엔드포인트 사양의 변경 사항이 모든 종속 케이스에 자동으로 전파되어, 이러한 사양 중심 접근 방식을 통해 유지 관리 부담을 줄일 수 있습니다.
주요 기능#
자동 URL 구성: Base URL + 엔드포인트 경로.
Base URL 예시#
세 개의 서비스가 있는 프로젝트를 가정해 보겠습니다.| 서비스 | Base URL(Prod) | 엔드포인트 경로 | 전체 URL |
|---|
| 사용자 | https://user.example.com | GET /user/{id} | https://user.example.com/user/{id} |
| 주문 | https://order.example.com | GET /order/{id} | https://order.example.com/order/{id} |
| 제품 | https://product.example.com | GET /product/{id} | https://product.example.com/product/{id} |
수동 {{BaseUrl}} 플레이스홀더가 필요하지 않습니다. Apidog은 모듈을 감지하고 올바른 Base URL을 자동으로 적용합니다.
요청 기능#
성공한 요청을 엔드포인트 사양으로 파싱할 수 있습니다. 임시 테스트 또는 문서화되지 않은 API에 사용할 수 있습니다.
요청은 API 사양이 사전에 정의되어 있지 않은 시나리오에 유연성을 제공하며, 설계 우선 워크플로와 요청 우선 워크플로 사이의 간극을 연결합니다.
테스트 시나리오#
테스트 시나리오(Test Scenario) 는 Postman Collections와 유사하게 요청 배치를 실행하며, 고급 자동화 기능을 제공합니다.고급 기능#
테스트 시나리오는 API 사양 변경 사항과 자동 동기화되어, API가 발전하더라도 테스트가 유효하게 유지되도록 합니다.
Design-first Mode 및 Request-first Mode#
Apidog의 API 모듈에는 인터페이스의 왼쪽 하단에서 전환할 수 있는 두 가지 모드인 Design-first Mode와 Request-first Mode가 있습니다.두 모드 모두 유사한 기능을 제공하지만, 서로 다른 팀 워크플로에 맞게 다른 인터페이스를 제공합니다.Design-first Mode#
API 설계 우선을 실천하는 팀에 권장됩니다.
개발 및 테스트 전에 API 사양을 정의합니다.
계획적이고 사양 중심인 프로젝트에 적합합니다.
Request-first Mode#
백엔드 개발을 먼저 중점적으로 진행하는 팀에 적합합니다.
요청을 생성한 다음, 성공한 호출에서 사양을 생성합니다.
문서화되지 않은 API 또는 타사 통합에 매우 적합합니다.
시작할 준비가 되셨습니까?#
처음부터 시작하기
Apidog를 처음부터 시작하십시오Apidog로 마이그레이션
Apidog로 마이그레이션하여 시작하십시오 