Apidog의 기본 URL을 사용하면 엔드포인트 주소의 반복되는 부분을 추출하여 통합 관리할 수 있습니다.
예를 들어, 엔드포인트가 https://api.example.com/v1/users인 경우, https://api.example.com/v1을 기본 URL로 설정할 수 있습니다. 그러면 엔드포인트 정의에서는 /users만 작성하면 됩니다.
요청을 보낼 때, Apidog는 기본 URL과 엔드포인트 경로를 자동으로 연결하여 완전한 요청 주소를 형성합니다. 이점은 서버 주소가 변경될 경우, 각 엔드포인트를 개별적으로 수정할 필요 없이 기본 URL만 업데이트하면 된다는 것입니다.
기본 URL 설정 단계
Apidog 프로젝트를 열고 우측 상단에서 "환경 관리(Environment Management)"를 찾으세요. Apidog는 기본적으로 개발, 테스트, 프로덕션과 같은 몇 가지 일반적인 환경을 생성합니다. 이러한 사전 설정을 사용하거나 필요에 따라 새로운 환경을 생성할 수 있습니다.
환경을 선택한 후 "기본 URL(Base URL)" 입력 상자가 표시됩니다. 프로토콜(http:// 또는 https://)로 시작하는 기본 주소를 입력하세요. 예를 들어 https://test.server.com과 같거나, https://api.example.com/v1처럼 버전 번호를 포함할 수 있습니다.
**후행 슬래시를 추가하지 마세요**. OpenAPI 사양에 따르면, 기본 URL은 /로 끝나서는 **안 되며**, 엔드포인트 경로는 /로 시작해야 **합니다**.
Apidog에서 더 나은 호환성과 완전한 기능 경험을 위해 OpenAPI 사양을 따르는 것을 권장합니다.
엔드포인트에서 기본 URL 사용하기
이제 새로운 엔드포인트를 생성할 때, URL 필드에 엔드포인트 경로만 입력하면 됩니다. 예를 들어, 사용자 목록 엔드포인트를 테스트하려면 /users만 입력하면 Apidog가 자동으로 이를 완전한 요청 URL인 https://api.example.com/v1/users로 결합합니다.
엔드포인트 경로에 /users/123/profile과 같이 여러 레벨이 포함된 경우에도 동일한 방법을 따를 수 있습니다. Apidog는 기본 URL과 경로를 자동으로 결합하여 완전한 요청 URL을 형성합니다.
참고: 엔드포인트 URL에 전체 주소(http:// 또는 https://로 시작)를 입력하면 기본 URL은 **사용되지 않습니다**. Apidog는 사용자가 제공한 전체 주소에 우선순위를 둡니다.
여러 환경에서 기본 URL 관리하기
대부분의 프로젝트는 여러 환경(개발, 테스트, 프로덕션)을 가지며, 각 환경마다 다른 서버 주소를 가집니다. 각 환경에 대해 다른 기본 URL을 설정할 수 있습니다.
예를 들어:
- 개발:
https://dev-api.example.com/v1 - 테스트:
https://test-api.example.com/v1 - 프로덕션:
https://api.example.com/v1
우측 상단에서 환경을 전환하면, 모든 엔드포인트는 선택된 환경의 서버 주소를 자동으로 사용합니다.
엔드포인트 주소 표시줄에서 직접 환경을 선택할 수도 있으며, 각 환경의 기본 URL이 표시됩니다. 이는 "환경 관리(Environment Management)" 패널에서 환경을 전환하는 것과 동일하게 작동합니다.
참고: 환경에 여러 기본 URL이 있는 경우, 기본 URL만 주소 표시줄에 나타납니다. 특정 엔드포인트에 기본이 아닌 기본 URL을 사용하려면 엔드포인트 내에서 수동으로 설정하거나 **모듈**을 통해 관리해야 합니다.
이러한 다중 기본 URL 설정은 마이크로서비스 아키텍처에서 일반적이며, 서로 다른 엔드포인트가 다른 서비스 주소를 사용해야 할 때 유용합니다.
마이크로서비스에서 기본 URL 관리하기
프로젝트가 마이크로서비스 아키텍처를 사용하고 모든 엔드포인트가 동일한 기본 URL을 공유하지 않는 경우, Apidog에서 기본 URL을 관리하는 두 가지 방법이 있습니다.
모듈 내에서 기본 URL 수동 지정
다른 서비스의 엔드포인트를 단일 모듈로 그룹화하고 특정 폴더 또는 개별 엔드포인트에 다른 기본 URL을 할당할 수 있습니다. 이 설정은 유연하며 중앙 집중식 관리를 선호하는 팀에 적합합니다.
예를 들어, 여러 서비스에 대해 여러 기본 URL을 가진 모듈을 구성할 수 있습니다.
그런 다음, **"사용자 서비스(User Service)"** 기본 URL을 user 폴더에 할당하고 **"주문 서비스(Order Service)"** 기본 URL을 order 폴더에 할당합니다. 각 폴더 내의 모든 엔드포인트는 해당 기본 URL을 자동으로 사용합니다.
폴더별로 구성하고 싶지 않다면, 개별 엔드포인트에 대한 기본 URL을 설정할 수도 있습니다. 엔드포인트의 “편집(Edit)” 페이지를 열고 드롭다운 메뉴에서 원하는 기본 URL을 선택하기만 하면 됩니다.
하지만 서비스 수가 증가함에 따라 이러한 방식으로 기본 URL을 관리하는 것은 번거롭고 유지보수가 어려워질 수 있습니다. 소규모 프로젝트에는 잘 작동할 수 있지만, 대규모 프로젝트는 빠르게 관리하기 어려워질 수 있습니다.
더 나은 확장성과 명확성을 위해, 더 구조화된 접근 방식을 권장합니다:
**각 서비스를 자체 모듈로 분리하고 모듈 수준에서 기본 URL을 설정하세요**. 이렇게 하면 프로젝트가 잘 정리되고 유지보수가 훨씬 쉬워집니다.
모듈별 서비스 구성 (권장)
각 서비스에 대해 별도의 모듈을 생성하고 "환경 관리(Environment Management)"에서 각 환경에 대한 기본 URL을 구성하세요. 이 접근 방식은 더 체계적이며 팀 협업 및 장기 유지보수에 이상적입니다.
예를 들어, **사용자 서비스(User Service)**, **주문 서비스(Order Service)**, **제품 서비스(Product Service)**에 대해 각각 자체 Swagger 또는 OpenAPI 사양 파일에 연결된 별도의 모듈을 생성할 수 있습니다.
모듈이 설정되면 "환경 관리(Environment Management)" 페이지로 이동하세요. 여기에서 모듈별로 깔끔하게 그룹화된 기본 URL 설정을 볼 수 있습니다.
각 환경은 동일한 모듈 구조를 공유하지만, 각 모듈의 기본 URL은 환경에 따라 다를 수 있습니다. 이를 통해 각 환경의 모든 모듈에 특정 기본 URL을 할당할 수 있습니다. 예를 들어:
이 설정을 사용하면 모듈 내에서 새 엔드포인트를 생성할 때마다 현재 환경에 맞는 올바른 기본 URL을 자동으로 사용하므로 수동으로 선택할 필요가 없습니다. 예를 들어:
- "사용자 서비스 모듈 및 프로덕션 환경"에서는 기본 URL이
https://user.example.com입니다. - "주문 서비스 모듈 및 테스트 환경"에서는
http://192.168.1.12:8080입니다.
"**모듈 + 환경**" 조합을 요청 URL을 정확하게 결정하는 좌표계로 생각하세요. 모듈과 환경이 올바르게 구성되어 있다면, Apidog는 각 요청에 대해 올바른 기본 URL을 자동으로 선택할 것입니다.
"이 엔드포인트는 어떤 주소를 사용하고 있지?"라고 궁금해할 필요가 없습니다. 적절한 모듈과 환경을 선택하기만 하면 Apidog가 나머지를 처리합니다.Ask ChatGPT
기본 URL 사용을 위한 실용적인 팁
- API에 버전 번호가 포함되어 있다면, 이를 기본 URL에 직접 추가하세요. 예를 들어:
https://api.example.com/v2. 이렇게 하면 API 버전을 업그레이드할 때 각 엔드포인트가 아닌 기본 URL만 업데이트하면 됩니다. - 타사 서비스를 호출하는 것과 같은 특별한 경우에는 엔드포인트에 전체 URL을 직접 입력할 수 있습니다. 이렇게 하면 기본 기본 URL이 자동으로 재정의됩니다.
결론
기본 URL을 효과적으로 관리하는 것은 API 프로젝트를 깔끔하고 확장 가능하며 유지보수하기 쉽게 유지하는 데 중요합니다. 특히 프로젝트의 복잡성이 증가할수록 더욱 그렇습니다. 단순한 단일 서비스 프로젝트를 작업하든 대규모 마이크로서비스 아키텍처를 작업하든, Apidog는 워크플로우에 맞춰 유연한 옵션을 제공합니다.
서비스를 모듈로 구성하고 환경별로 기본 URL을 설정함으로써, 수동 오버헤드 없이 각 엔드포인트가 항상 올바른 서버를 가리키도록 보장할 수 있습니다. 스마트한 기본 설정, 환경 전환 및 모듈식 설계를 통해 Apidog는 프로세스를 단순화하고 추측 작업을 없애줍니다.