REST

SoftLayer는 RPC 유형 API 서비스뿐만 아니라 RESTful API를 제공합니다. 프로그래밍 언어가 SOAP 또는 XML-RPC를 완전하게 지원하지는 않지만 단일 HTTP 프로토콜 조치를 수행하고 XML 또는 JSON 데이터를 해석할 수 있는 경우 REST API를 사용하십시오.

REST URL

REST API URL은 SoftLayer 오브젝트 계층 구조를 쉽게 이동할 수 있는 구조로 되어 있습니다. 기본 REST 요청의 구조는 다음과 같습니다.

https://[username]:[apiKey]@api.[service.]softlayer.com/rest/v3/[serviceName]/[initializationParameter].[returnDatatype]
  • 프라이빗 네트워크 요청을 비롯하여 모든 REST 요청이 HTTP SSL을 통해 전달되어야 합니다.
  • HTTP 인증을 통해 요청을 인증하려면 API 사용자 이름과 키를 사용합니다.
  • REST 요청의 기본 호스트 이름과 폴더 이름은 api.softlayer.com/rest/v3/ 또는 api.service.softlayer.com/rest/v3/입니다. SoftLayer 프라이빗 네트워크를 통해 REST API를 액세스하려면 api.service.softlayer.com/rest/v3/을 사용합니다. SoftLayer와 더 안전하게 통신할 수 있는 방법이지만, API를 호출하는 시스템이 SoftLayer 프라이빗 네트워크에 있어야 합니다(SoftLayer에서 구매한 것이거나 SoftLayer 프라이빗 네트워크 VPN에 로그인된 상태).
  • 기본 URL 뒤에 호출할 API 서비스의 이름을 붙입니다(예: "SoftLayer_Account" 또는 "SoftLayer_Hardware_Server").
  • API 요청이 초기화 매개변수를 요구하는 경우, 슬래시와 이어서 초기화 매개변수 id를 URL에 추가합니다.
  • SoftLayer REST API에서 XML 또는 JSON 형식 출력을 리턴합니다. 요청 끝에 ".xml" 또는 ".json"을 추가하여 수신하는 데이터의 형식을 지정합니다.

이와 같은 요청은 호출하려는 API 서비스의 getObject() 메소드를 호출합니다. SoftLayer_Account::getObject는 초기화 매개변수를 요구하지 않으므로 REST URL이 다음과 같습니다.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account.json

하지만, 특정 SoftLayer_Hardware_Server 레코드의 getObject() 메소드를 호출하려면 검색하려는 서버의 id가 "1234"라는 가정 하에 다음 URL을 사용합니다.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Hardware_Server/1234.json

초기화 매개변수 뒤에 메소드 이름을 지정하여 getObject()가 아닌 API 메소드를 호출합니다. 메소드가 "get"으로 시작하는 경우, 메소드 이름에서 "get" 단어를 제거하고 첫 번째 문자를 대문자로 바꿉니다. 오브젝트의 관계형 특성에 빠르게 액세스하려는 경우에도 이 메소드를 사용할 수 있습니다. 예를 들어, SoftLayer_Account API 서비스의 getHardware() 메소드와 hardware 관계형 특성은 다음에서 접근할 수 있습니다.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json

마찬가지로, 서버의 네트워크 구성요소는 다음 URL을 통해 접근합니다.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Hardware_Server/1234/NetworkComponents.json

초기화 매개변수 id와 관계형 특성 조합을 연결하여 특정 오브젝트 구성요소의 상세 정보를 확인합니다. 추가한 모든 id는 해당 특정 관계형 특성의 상세 정보를 확인합니다. 예를 들어, id 5678인 서버 1234의 네트워크 구성요소를 가져오려는 경우, 다음 URL을 사용합니다.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Hardware_Server/1234/NetworkComponents/5678.json

해당 네트워크 구성요소의 업링크 연결을 가져오려면 다음을 사용합니다.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Hardware_Server/1234/NetworkComponents/5678/uplinkNetworkComponents.json

HTTP 요청 유형

DELETE

HTTP DELETE 요청은 서비스의 deleteObject() 메소드 대신 오브젝트를 삭제하는 데 사용합니다. 예를 들어, SoftLayer의 DNS 서버에서 도메인 레코드 1234를 제거하려면 HTTP DELETE 요청을 다음 URL로 전달합니다.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Dns_Domain/1234.json

GET

HTTP GET 요청은 간단한 오브젝트 검색과 메소드 호출에 사용합니다. 예를 들어, URL에 HTTP GET 요청을 보내 도메인 레코드 id 1234를 검색합니다.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Dns_Domain/1234.json

POST

HTTP POST 요청은 서비스의 createObject() 또는 createObjects() 메소드 대신 오브젝트를 작성하는 데 사용합니다. 오브젝트의 기본 폼 구조와 API 서비스의 createObject() 메소드에 필요한 그 외 매개변수를 포함한 하나의 "매개변수" 요소가 포함된 단일 JSON 또는 XML 구조를 POST합니다. 예를 들어, SoftLayer의 DNS 서버에 도메인 레코드를 작성하려면 다음 데이터와 함께 HTTP POST 요청을 다음 URL로 전달합니다.

{
    "parameters" : [
        {
            "name" : "example.org",
            "resourceRecords" : [
                {
                    "type" : "a",
                    "host" : "@",
                    "data" : "127.0.0.1"
                }
            ]
        }
    ]
}
https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Dns_Domain.json

PUT

HTTP PUT 요청은 서비스의 editObject() 또는 editObjects() 메소드 대신 오브젝트를 편집하는 데 사용합니다. 오브젝트의 기본 폼 구조와 API 서비스의 editObject() 메소드에 필요한 그 외 매개변수를 포함한 하나의 "매개변수" 요소가 포함된 단일 JSON 또는 XML 구조를 PUT합니다. 예를 들어, SoftLayer DNS 서버의 도메인 레코드 내에서 도메인 자원 레코드 5678을 편집하려면 다음 데이터와 함께 HTTP PUT 요청을 다음 URL로 전달하고 data를 "10.0.0.1"로 변경합니다.

{
    "parameters" : [
        {
            "data" : "10.0.0.1",
        }
    ]
}
https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Dns_Domain/1234/ResourceRecords/5678.json

메소드 매개변수 전달

당사 REST API를 통해 매개변수를 전달하려면 각 매개변수를 URL 경로에 추가합니다.
이들 매개변수는 문서에 표시된 것과 동일한 순서대로 위에서 아래로 전달되어야 합니다.

예를 들어, SoftLayer_Monitoring_Agent::setActiveAlarmSubscriber는 userRecordId 매개변수를 요구합니다.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Monitoring_Agent/1234/setActiveAlarmSubscriber/5678.json

일부 메소드는 SoftLayer_Dns_Domain_ResourceRecord::createObjects와 같은 배열인 하나의 매개변수를 요구합니다.

 {
  "parameters":
    [
      [
        {"host":"hosta","data":"127.0.0.1","ttl":"900","type":"a","domainId":"1234"}
        ,
        {"host":"hostb","data":"127.0.0.1","ttl":"900","type":"a","domainId":"1234"}
      ]
    ]
}

매개변수 및 리턴 형식을 설정하는 대체 방법

".json" 및 ".xml"을 REST URL에 추가하는 방법 외에, 요청의 HTTP Accept 또는 Content-Type 헤더에 MIME 형식(JSON에는 application/json, XML에는 text/xml)을 전달하여 API 호출 리턴 형식을 설정할 수도 있습니다.

오브젝트 마스크 사용

API 호출 URL에 오브젝트 마스크를 작성하려면 objectMask 변수를 쿼리 문자열에 추가합니다. 오브젝트 마스크는 연결된 관계형 특성을 마침표로 구분하고 세미콜론으로 나누어 표시한 관계형 특성 목록입니다. 쿼리 문자열에서 공간 절약을 위해 REST 오브젝트는 쿼리하는 API 서비스가 아닌 URL 끝에 있는 데이터 유형에 맞춰 표시됩니다. 마찬가지로, REST 오브젝트 마스크에는 mask 특성이 포함되어 있지 않습니다.

다음 URL은 하드웨어가 있는 데이터 센터와 계정의 하드웨어 레코드를 검색하는 오브젝트 마스크를 작성합니다. 오브젝트 마스크에 계정이 아닌 하드웨어와 관련하여 검색할 관계형 특성만 포함되어 있는 점에 유의하십시오.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json?objectMask=datacenter

이 URL은 하드웨어의 연결된 데이터 센터, 운영 체제, 네트워크 구성요소 레코드와 함께 계정의 하드웨어 레코드를 가져옵니다. 이 관계형 항목은 세미콜론으로 구분됩니다.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json?objectMask=datacenter;operatingSystem;networkComponents

이 URL은 하드웨어의 연결된 데이터 센터, 운영 체제, 운영 체제 비밀번호, 네트워크 구성요소 레코드와 함께 계정의 하드웨어 레코드를 가져옵니다. 연결된 관계형 특성은 마침표로 구분됩니다.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json?objectMask=datacenter;operatingSystem.passwords;networkComponents

REST API는 SoftLayer의 SOAP 및 XML-RPC API와 약간 다른 방식으로 오브젝트 마스크를 처리합니다. REST 오브젝트 마스크는 만들어 SoftLayer API에서 검색되는 로컬 데이터 유형 특성을 필터링할 수 있습니다. 로컬 특성을 마스크에 정의하는 경우, SoftLayer API에서 마스크가 필터로 처리되고 마스크에 지정된 로컬 특성만 검색합니다. 예를 들어, 이 URL은 계정의 하드웨어 레코드에서 id 및 hostname 특성만 검색합니다.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/Hardware.json?objectMask=hardware.id;hardware.hostname

결과 제한 사용

API 호출에서 결과의 수를 제한하려면 resultLimit 변수를 쿼리 문자열에 추가합니다. 쉼표로 구분된 두 개 숫자에 resultLimit 변수를 설정합니다.

  • 결과 세트를 시작하는 오프셋.
  • 호출에서 제한되는 결과의 수.

이 URL은 계정에 열려 있는 처음 두 개 티켓을 검색하고 SoftLayer_Account::getOpenTickets 메소드를 호출합니다.

https://username:apiKey@api.softlayer.com/rest/v3/SoftLayer_Account/OpenTickets.json?resultLimit=0,2

오류 처리

SoftLayer REST API가 API 호출에서 리턴되는 오류 메시지가 표시된 단일 error 노드가 있는 XML 또는 JSON 출력을 리턴합니다. 예를 들어, 존재하지 않는 서비스에 대한 URL입니다.
https://username:apiKey@api.softlayer.com/rest/v3/Nonexistent.xml
다음 오류를 리턴합니다.

>
   Service does not exist>
>

JSON 동일 항목인 경우:

https://username:apiKey@api.softlayer.com/rest/v3/Nonexistent.json

다음 오류를 리턴합니다.

{
    "error": "Service does not exist"
}

인증 오류

REST URL을 요청할 때 올바르지 않은 사용자 이름/API 키 조합을 사용하는 경우, SoftLayer REST API에 HTTP 401 권한이 없음 오류가 리턴됩니다.

주의 사항

복합 유형 지정

XML-RPC와 마찬가지로, REST API는 특정 매개변수에서 확장된 복합 유형을 판별할 수 없습니다. 이 경우, 메소드로 전송하는 오브젝트 유형에 설정된 복합 매개변수에 complexType 특성을 정의해야 합니다.

참조된 API 구성요소

서비스

데이터 유형

메소드