API 기본 사항
웹 서비스 API에서 HTTP 통신에는 요청 응답 주기가 포함됩니다.
요청의 URL 요소입니다
사용되는 프로그래밍 언어나 도구에 관계없이 웹 서비스 API에 대한 각 호출은 URL, HTTP 동사 및 Accept 헤더와 유사한 구조를 가집니다.
모든 요청은 다음 예제와 같이 URL을 포함하며 표에 설명된 요소를 포함합니다.
(https://webservices.name.com:8443/devmgr/v2/storage-systems`)
영역 | 설명 |
---|---|
HTTP 전송 'https://' |
웹 서비스 프록시를 사용하면 HTTP 또는 HTTPS를 사용할 수 있습니다. 임베디드 웹 서비스는 보안상의 이유로 HTTPS가 필요합니다. |
기본 URL 및 포트입니다 "webservices.name.com:8443` |
각 요청은 웹 서비스의 활성 인스턴스로 올바르게 라우팅되어야 합니다. 수신 대기 포트와 함께 인스턴스의 FQDN(정규화된 도메인 이름) 또는 IP 주소가 필요합니다. 기본적으로 웹 서비스는 포트 8080(HTTP의 경우) 및 포트 8443(HTTPS의 경우)을 통해 통신합니다. 웹 서비스 프록시의 경우 프록시 설치 중에 또는 wsconfig.xml 파일에서 두 포트를 모두 변경할 수 있습니다. 다양한 관리 애플리케이션을 실행하는 데이터 센터 호스트에서 포트 경합이 흔히 발생합니다. Embedded Web Services의 경우 컨트롤러의 포트를 변경할 수 없습니다. 보안 연결의 경우 기본적으로 포트 8443이 됩니다. |
API 경로 devmgr/v2/storage-systems를 선택합니다 |
Web Services API 내의 특정 REST 리소스 또는 끝점에 대한 요청이 이루어집니다. 대부분의 끝점은 다음과 같습니다. devmgr/v2/<resource>/[id]' API 경로는 다음 세 부분으로 구성됩니다.
|
지원되는 HTTP 동사
지원되는 HTTP 동사에는 GET, POST 및 DELETE가 포함됩니다.
-
가져오기 요청은 읽기 전용 요청에 사용됩니다.
-
POST 요청은 개체를 만들고 업데이트하는 데 사용되며, 보안과 관련이 있을 수 있는 읽기 요청에도 사용됩니다.
-
삭제 요청은 일반적으로 관리에서 개체를 제거하거나, 개체를 완전히 제거하거나, 개체의 상태를 다시 설정하는 데 사용됩니다.
현재 웹 서비스 API는 PUT 또는 패치를 지원하지 않습니다. 대신 POST를 사용하여 이러한 동사에 대한 일반적인 기능을 제공할 수 있습니다. |
머리글 적용
요청 본문을 반환할 때 Web Services는 달리 지정하지 않는 한 데이터를 JSON 형식으로 반환합니다. 일부 클라이언트는 기본적으로 ""text/html"" 또는 이와 유사한 것을 요청합니다. 이러한 경우 API는 HTTP 코드 406으로 응답하여 이 형식의 데이터를 제공할 수 없음을 나타냅니다. 가장 좋은 방법은 JSON을 응답 유형으로 기대하는 모든 경우에 Accept 헤더를 ""application/json""으로 정의하는 것입니다. 응답 본문이 반환되지 않은 경우(예: 삭제), 수락 헤더를 사용해도 의도하지 않은 효과가 발생하지 않습니다.
응답
API에 대한 요청이 이루어지면 응답이 두 가지 중요한 정보를 반환합니다.
-
HTTP 상태 코드 — 요청이 성공했는지 여부를 나타냅니다.
-
선택적 응답 본문 — 일반적으로 실패의 특성에 대한 자세한 정보를 제공하는 리소스 또는 바디의 상태를 나타내는 JSON 바디를 제공합니다.
결과 응답 본문의 모양을 확인하려면 상태 코드와 콘텐츠 형식 헤더를 확인해야 합니다. HTTP 상태 코드 200-203 및 422의 경우 Web Services는 응답으로 JSON 본문을 반환합니다. 다른 HTTP 상태 코드의 경우, Web Services는 일반적으로 추가 JSON 본문을 반환하지 않습니다. 이는 사양이 이를 허용하지 않거나(204) 상태가 자체 설명이기 때문입니다. 이 표에는 일반적인 HTTP 상태 코드 및 정의가 나와 있습니다. 또한 각 HTTP 코드와 관련된 정보가 JSON 본문에서 반환되는지 여부도 나타냅니다.
HTTP 상태 코드입니다 | 설명 | JSON 바디 |
---|---|---|
200 정상 |
성공적인 응답을 나타냅니다. |
예 |
201 생성됨 |
개체가 생성되었음을 나타냅니다. 이 코드는 200 상태가 아닌 몇 가지 드문 경우에 사용됩니다. |
예 |
202 수락됨 |
요청이 비동기 요청으로 처리되도록 허용되었지만 실제 결과를 얻으려면 후속 요청을 해야 함을 나타냅니다. |
예 |
203 권한 없는 정보입니다 |
200개의 응답과 비슷하지만 웹 서비스는 데이터가 최신 데이터임을 보장할 수 없습니다(예: 현재 캐시된 데이터만 사용 가능). |
예 |
204 콘텐츠 없음 |
작업이 성공했지만 응답 본문이 없음을 나타냅니다. |
아니요 |
400 잘못된 요청 |
요청에 제공된 JSON 본문이 유효하지 않음을 나타냅니다. |
아니요 |
401 승인되지 않음 |
인증 실패가 발생했음을 나타냅니다. 자격 증명이 제공되지 않았거나 사용자 이름 또는 암호가 잘못되었습니다. |
아니요 |
403 사용 금지 |
인증 실패 - 인증된 사용자에게 요청된 끝점에 액세스할 수 있는 권한이 없음을 나타냅니다. |
아니요 |
404를 찾을 수 없습니다 |
요청한 리소스를 찾을 수 없음을 나타냅니다. 이 코드는 존재하지 않는 API 또는 ID에서 요청한 존재하지 않는 리소스에 대해 유효합니다. |
아니요 |
422 처리할 수 없는 엔터티 |
요청이 일반적으로 제대로 구성되었지만 입력 매개 변수가 잘못되었거나 스토리지 시스템의 상태가 웹 서비스가 요청을 충족시킬 수 없음을 나타냅니다. |
예 |
424 실패한 종속성 |
웹 서비스 프록시에서 요청된 스토리지 시스템을 현재 액세스할 수 없음을 나타내는 데 사용됩니다. 따라서 웹 서비스가 요청을 충족할 수 없습니다. |
아니요 |
429 요청이 너무 많습니다 |
요청 한도를 초과했으며 나중에 다시 시도해야 함을 나타냅니다. |
아니요 |
샘플 스크립트
GitHub에는 NetApp SANtricity 웹 서비스 API를 사용하는 것을 보여주는 샘플 스크립트의 수집 및 구성을 위한 저장소가 포함되어 있습니다. 리포지토리에 액세스하려면 를 참조하십시오 "NetApp 웹 서비스 샘플".