GEN/CIVIL NX API를 사용하기 위해서는 base URL과 API Key를 이해하는 것이 필수입니다.
이 페이지를 읽기 전에, 아래 문서를 먼저 이해하시는 것을 권장합니다.
baseURL
REST API에서 baseURL은 API 엔드포인트*의 기본 URL을 의미합니다. 즉, API 서버와 통신하는 모든 HTTP 요청에서 공통으로 사용되는 기본 주소를 정의합니다.
일반적으로 baseURL은 API의 루트 주소 역할을 하며, 모든 엔드포인트의 상대 주소는 이 루트를 기준으로 결정됩니다. 예를 들어, 아래와 같은 간단한 REST API가 있다고 가정해 보겠습니다.
Base URL: https://api.example.com
Endpoints:
- /users
- /posts
- /comments 이 경우 baseURL은 https://api.example.com 이며, 엔드포인트인 "/users", "/posts", "/comments"는 모두 baseURL을 기준으로 한 상대 경로입니다.
따라서 사용자 정보를 조회하는 엔드포인트는 https://api.example.com/users 가 되고, 게시글 정보를 조회하는 엔드포인트는 https://api.example.com/posts 가 됩니다.
baseURL을 사용하면 매 요청마다 서버 주소를 반복해서 입력하지 않아도 되므로, 코드가 단순해지고 유지관리도 쉬워집니다.
*endpoint: REST API에서 특정 리소스 또는 서비스에 접근하기 위한 URL 경로를 의미합니다.
API Key
API Key는 웹 API를 사용하는 개발자 또는 애플리케이션에 인증 및 접근 권한을 부여하는 보안 문자열입니다. 일반적으로 문자열 형태로 제공되며, API 호출을 수행하는 클라이언트를 식별하고 인증하는 역할을 합니다. API Key의 주요 역할은 다음과 같습니다.
- 인증 및 접근 제어: API Key는 API 서버에 요청을 보내는 클라이언트를 식별하고 인증합니다. 서버는 올바른 API Key가 포함된 요청만 허용하고 처리합니다.
- 사용자 식별: API Key를 통해 어떤 사용자 또는 애플리케이션이 API를 사용했는지 식별할 수 있습니다. 이는 로그 기록, 분석, 사용량 추적 등에 유용합니다.
- 접근 권한 및 권한 관리: API Key는 클라이언트별 접근 수준을 관리하고 권한을 부여하는 데 사용됩니다. 이를 통해 특정 API 엔드포인트나 기능에 대한 제한 또는 허용을 설정할 수 있습니다.
- 보안 강화: API Key는 API 오용 시도에 대한 추가적인 보안 계층 역할을 합니다. 특히 공개 API의 경우, API Key가 노출되면 서버 또는 클라이언트 측에서 악용 및 무단 사용을 방지하기 위한 조치가 필요할 수 있습니다.
API Key는 일반적으로 HTTP 요청 헤더 또는 요청 파라미터에 포함됩니다. 예를 들어, API Key를 요청에 포함하는 일반적인 방법은 다음과 같습니다.
API Key 포함 방식:
- 헤더(Header): HTTP 요청 헤더에 API Key를 전달합니다. 보통 Authorization 또는 사용자 정의 헤더 형태로 포함됩니다.
- 요청 파라미터(Request Parameter): URL의 쿼리 문자열에 API Key를 포함하여 요청합니다.
API Key는 민감한 정보이므로 안전하게 저장하고 전송하는 것이 중요합니다. 또한 API 제공자가 안내하는 API Key 생성 및 관리 지침을 따르는 것이 좋습니다.
GEN/CIVIL NX API의 base URL과 API Key
GEN/CIVIL NX API는 base URL과 API-Key 개념을 모두 사용합니다.
base URL은 제품 사용 환경, 국가, 서버 등에 따라 달라질 수 있습니다. 아래의 제품 경로를 통해 확인할 수 있습니다.
GEN/CIVIL NX API에서 API-Key는 MAPI-Key라고 하며, REST API 요청 시 반드시 헤더에 포함되어야 합니다. 따라서 헤더에 “MAPI-Key”를 추가하고, 해당 값에 제품에서 제공하는 키 값을 입력해야 정상적으로 동작합니다. MAPI-Key 또한 base URL과 유사하게 아래의 제품 경로를 통해 확인할 수 있습니다.
예시
MAPI-Key는 왜 변경될 수 있나요?
MAPI-Key는 서버에 연결되는 특정 MIDAS 제품을 식별하는 중요한 파라미터입니다. 사용자의 PC 또는 네트워크 환경에 따라 제품이나 사용자별로 고정된 값을 부여하는 방식은 보안 위협이 될 수 있습니다.
키가 유출될 경우, 해당 키를 이용해 사용자의 제품이 원격으로 제어될 위험이 있습니다. 이러한 위험을 줄이기 위해, MAPI-Key 개념 대신 무작위로 생성되는 임시 키를 사용하는 방식도 대안이 될 수 있습니다.