API Explorer

API Explorer를 사용하여 REST API에 대해 알아봅니다. 또한, 다양한 방법 및 리소스를 테스트하여 올바르게 구성하고 있는지 확인할 수 있습니다. 코드에 시작점으로 JSON 모델을 복사하여 붙여넣을 수 있습니다.


팁

API Explorer의 목적은 API에 대해 알아보는 데 도움이 되는 것입니다. API Explorer를 통한 호출을 테스트하려면 일반적인 작업을 방해할 수 있는 액세스 잠금을 생성해야 합니다. 프로덕션이 아닌 디바이스에서 API Explorer를 사용하는 것이 좋습니다.

API Explorer 열기

API Explorer에서는 프로그래밍 용도로 사용할 수 있는 모든 리소스 및 JSON 개체에 대해 설명합니다. API Explorer는 각 개체의 '특성-값' 쌍에 대한 자세한 정보를 제공합니다. 따라서 다양한 HTTP 방법을 실험하여 각 리소스를 사용하는 데 필요한 코딩을 파악할 수 있습니다.

프로시저

단계 1

브라우저를 사용하여 시스템의 홈페이지(예: https://ftd.example.com)를 엽니다.

단계 2

device manager에 로그인합니다.

단계 3

(6.4 및 이전 버전) /#/api-explorer를 가리키도록 URL을 편집합니다(예: https://ftd.example.com/#/api-explorer).

단계 4

(6.5 이상 버전) More options(추가 옵션) 버튼(추가 옵션 버튼)을 클릭하고 API Explorer를 선택합니다.

브라우저 설정에 따라 별도의 탭 또는 창에 API Explorer가 열립니다.

API Explorer 사용 방법

API Explorer를 시작하면 리소스 그룹의 목록이 함께 표시됩니다. 이 그룹에는 API에서 사용할 수 있는 리소스가 포함되어 있습니다. 다음 그림에는 목록의 일부 샘플이 나와 있습니다.


API Explorer의 리소스 목록입니다.

이러한 그룹 이름은 링크입니다. 링크를 클릭하여 그룹을 열면 해당 그룹의 리소스에 사용할 수 있는 방법이 표시됩니다. 각 그룹의 오른쪽에는 다음과 같은 명령도 있습니다.

  • Show/Hide(표시/숨기기) - 그룹을 열고 닫습니다. 이는 그룹 이름을 클릭하는 것과 같습니다. 그룹을 처음 펼치면 방법이 간단히 표시(List Operations(작업 나열)와 동일)되지만, 그 이후에는 시스템에서 그룹을 닫기 전에 마지막으로 펼쳤던 상태를 기억하여 그룹을 다시 열 때 이전 상태 그대로 펼칩니다.

  • List Operations(작업 나열) - 그룹의 각 리소스에 사용할 수 있는 HTTP 방법을 표시합니다. 이 정보에는 각 리소스의 URL(Universal Resource Locator) 템플릿에 대한 상대 경로가 포함되어 있습니다. 경로 변수는 표준 규칙인 {variable} 형식으로 표시되며, {variable} (중괄호 포함)은 적절한 값으로 대체해야 합니다. 기본 URL을 이 상대 경로에 추가해야 합니다. API의 기본 URL의 내용을 참조하십시오.

    해당 방법에 대한 전체 설명서를 참조하려면 작업 URL 템플릿을 클릭합니다.

  • Expand Operations(작업 확장) - 그룹에서 사용 가능한 모든 HTTP 방법 및 리소스를 엽니다.

하위 리소스가 많이 있는 그룹도 있습니다. 예를 들어, DataInterface ManagementAccess 그룹은 /devicesettings/default/managementaccess에 대한 GET, POST 및 DELETE 작업과 /devicesettings/default/managementaccess/{objId}에 대한 GET 및 PUT 작업을 포함합니다.


API Explorer의 한 카테고리에 대한 리소스 목록입니다.

리소스 설명서 보기

각 리소스의 속성에 대한 설명서가 API Explorer에 있습니다.

프로시저

단계 1

관심 있는 특정 리소스 및 방법에 대한 내용을 드릴다운합니다.

단계 2

Response Class(응답 클래스) 섹션에서 Model(모델) 탭을 클릭합니다.

모델에는 설명 및 데이터 유형과 함께 특성이 나열되어 있습니다. GET의 경우 반환될 수 있는 paging 옵션도 있습니다. 응답에 반환된 개체보다 더 많은 개체가 있는 경우, 개체의 다음 및 이전 배치용 URL을 얻습니다.

예를 들어, 다음 그래픽에는 Model(모델) 탭이 선택된 상태의 POST /object/tcpports 방법 및 리소스가 나와 있습니다. 기본적으로 Example Value(예시 값) 탭이 선택되므로 설명서를 보려면 항상 Model(모델)을 클릭해야 합니다.


API Explorer의 POST object/tcpports 설명서입니다.

개체 ID(objId) 및 상위 ID 찾기

일부 리소스에는 다음과 같이 URL에 개체 ID 또는 관련된 상위 개체 ID가 필요합니다.

  • PUT /object/networks/{objId}

  • GET /policy/intrusionpolicies/{parentId}/intrusionrules

대부분의 경우 GET 방법을 사용하여 리소스 계층 구조에서 한 레벨 높은 개체 또는 상위 ID를 얻을 수 있습니다. 개체/상위 ID는 해당 개체에 대한 id 파라미터의 UUID입니다.

예를 들어 GET /object/networks는 현재 정의된 모든 네트워크 개체의 목록을 반환합니다. 원하는 개체로 이동하려면 호출을 여러 번 수행하여 목록 전체를 확인해야 할 수 있습니다. 또는 limit 쿼리 파라미터를 포함하여 한 번의 호출에 반환되는 개체 수를 늘려야 할 수 있습니다. 각 개체의 형식은 다음과 같습니다(개체 ID는 강조 표시되어 있음). 


{
      "version": "9bbb9e5d-8115-11e7-8cb4-772d7eb1894d",
      "name": "any-ipv4",
      "description": null,
      "subType": "NETWORK",
      "value": "0.0.0.0/0",
      "isSystemDefined": true,
      "id": "9bbbc56e-8115-11e7-8cb4-01865c95f930",
      "type": "networkobject",
      "links": {
        "self": "https://ftd.example.com/api/fdm/최신/object/networks/
9bbbc56e-8115-11e7-8cb4-01865c95f930"
      }

참고

가끔 {objId}가 계층 구조의 최상위 레벨에서 발생하는 경우가 있습니다. 이러한 경우, 때때로 개체 ID에 대한 값을 입력하여 동일한 결과를 얻을 수 있습니다. 다른 경우에는 개체 모델 설명서에서 유효한 개체 유형(ID는 유효한 유형 중 하나)에 대한 내용을 확인하십시오. 이는 항상 GET 호출 (예: GET /operational/systeminfo/{objId} 및 GET /operational/featureinfo/{objId})입니다.

오류 카탈로그 보기 및 오류 메시지 평가

REST API로서, 시스템에서는 존재하지 않는 개체에 대해 GET을 수행하는 경우 404 같은 표준 HTTP 오류 코드를 반환합니다.

또한, 시스템에는 더 구체적으로 오류를 설명하는 여러 오류 메시지가 포함되어 있습니다. API 호출로 인해 오류가 발생하는 경우 응답 본문에는 더 구체적인 메시지가 포함될 수 있습니다.

예를 들어 다음 네트워크 개체에 대해 POST /object/networks 작업을 시도하면 오류 메시지가 표시됩니다. 이 경우 네트워크를 지정하려고 시도하지만 넷마스크를 포함하지는 않습니다. 즉, 값은 10.10.10.0/24 또는 10.10.10.0/255.255.255.0 중 하나여야 합니다. 


{
  "name": "test-network",
  "subType": "NETWORK",
  "value": "10.10.10.0",
  "type": "networkobject"
}

그 결과 HTTP 응답 코드는 422이고, 특정 오류 메시지를 포함하는 응답 본문은 다음과 같습니다.


{
  "error": {
    "severity": "ERROR",
    "key": "Validation",
    "messages": [
      {
        "description": "The type Network requires a netmask. To specify a single host, either use the type Host, or use {0}/255.255.255.255.",
        "code": "networkWithoutNetmask",
        "location": "value"
      }
    ]
  }
}

다음 절차에서는 응답 본문에서 반환될 수 있는 오류 메시지의 목록을 보는 방법에 대해 설명합니다.

프로시저

단계 1

device manager에서 More options(추가 옵션) 버튼(추가 옵션 버튼)을 클릭하고 API Explorer를 선택합니다.

단계 2

목차에서 Error Catalog(오류 카탈로그)를 클릭합니다.

메시지에는 다음과 같은 구성 요소가 포함됩니다.

  • Category(카테고리) - 메시지의 일반적인 유형입니다. 이 값은 오류 응답 본문의 key 특성에 표시됩니다. 카테고리에는 Validation(검증), General(일반) 및 Deployment(구축)가 포함됩니다.

  • Code(코드) - 오류 메시지를 식별하는 고유한 문자열입니다. 이 값은 오류 응답 본문의 code 특성에 표시됩니다. 브라우저의 Find On Page(페이지에서 찾기) 기능을 사용하면 이 값을 사용하여 카탈로그에서 메시지를 찾을 수 있습니다.

  • Message(메시지) - 오류를 설명하는 특정한 메시지입니다. 이 값은 오류 응답 본문의 description 특성에 표시됩니다. 메시지 내의 변수는 {0}, {1} 등으로 표시됩니다.