들어가며

운영체제(OS)에 그래픽 사용자 인터페이스(GUI)가 등장하면서 컴퓨터와 관련된 환경이 크게 바뀌었다.
GUI를 통해 컴퓨터는 더 이상 전문가의 도구가 아닌 누구나 사용할 수 있는 도구로 우리 생활 속에 자리 잡게 되었고, 그 변화 중 하나로 조작의 편의성을 꼽을 수 있다.

하지만 모든 일에는 앞과 뒤가 있듯이 반드시 좋은 영향만 있었던 것은 아니다.
기존의 명령줄 인터페이스(CLI)에 비해 일반 사용자의 편의성을 크게 향상시킨 GUI는 편리함 대신 시각적 처리 때문에 컴퓨터의 성능이 저하되거나 세밀한 제어가 어렵고, 숙달되면 오히려 조작이 느려지는 등의 문제가 발생하기도 했다. 이른바 익숙해진 전문가 입장에서 보면 비효율적인 요소가 크다.
그래서 현존하는 OS는 종류를 불문하고 GUI와 CLI를 함께 제공하고 있습니다.

전문 ETL 툴인 저희 Xplenty는 노코드/로우코드 툴로서 데이터 파이프라인 구축에 GUI 환경을 제공하고 있습니다. 하지만 위의 OS의 예처럼 데이터 파이프라인 구축과 운영에 익숙해지면 GUI를 통한 조작이 번거로울 수 있습니다.

이를 위해 Xplenty에서는 CLI 기반으로 이용할 수 있는 Rest API를 제공하고 있습니다. 
이번 글에서는 Xplenty가 제공하는 Rest API 중 리소스 열람용에 대해 자세히 알아보겠습니다.

사전 준비

제한 사항

이 글은 아래와 같은 전제를 가지고 설명합니다. 양해 부탁드립니다.

1. 데이터 파이프라인(Xplent에서는 패키지)은 이미 생성되어 있다.
2. Crul, Postman, Insomnia 등의 HTTP/HTTPS 클라이언트 사용 경험이 있다.
3. Rest API 조작에 익숙하다.
4. API에 대한 자세한 내용은 github(영어)를 참고하시기 바랍니다.

Xplenty Rest API 기본 정보

Xplenty의 Rest API는 Xplenty가 제공하는 HTTPS 기반의 RESTful API 모음으로, 사용 방법도 일반적인 RESTful API 사용과 차이가 없습니다.
이 글에서는 github의 내용을 기준으로 Rest API의 실습을 진행하고자 합니다.

• Rest API URL

  • https://api.xplenty.com/<account_id>/api/<reosource_name
    • <account_id>는 Xplenty의 Settings - Accounting Settings - Profile에서 확인할 수 있다.

• • <reosurce_name>에 대해서는 Xplenty의 주요 리소스 소개 부분을 참고하시기 바랍니다.

• 인증 방식

  • HTTP Basic을 사용하고 있으며, 모든 Xplenty Rest API는 인증이 반드시 필요합니다.
  • 사용자 이름은 Xplenty의 API KEY를 지정하며, 비밀번호는 지정할 필요가 없다.
    • curl로 지정 - -d <API_KEY>: 
  • <API KEY>는 Xplenty의 Settings - Developer Settings - Access token에서 조회할 수 있다.

• • 단, 현재 API KEY 요청은 Live Chat을 통해 문의해 주시기 바랍니다!

• 호출 횟수 제한

  • 사용자당 1시간에 5000회의 호출 횟수 제한(credit)이 있습니다.
  • 지정된 호출 횟수 초과 시 429 Too Many Requests를 반환한다.

Rest API 호출 예시

이제 Xplenty의 Rest API 호출 샘플을 각각의 HTTP/HTTPS 클라이언트를 통해 소개하겠습니다.
예시 설명은 List Jobs를 사용하여 HTTP/HTTPS 클라이언트 상에서 API 호출을 수행합니다.
Xplenty가 제공하는 모든 API의 목록은 이 링크를 참고하시기 바랍니다.

GUI 앱을 통한 호출

잘 알려진 HTTP/HTTPS 클라이언트인 Postman과 Insomnia를 사용하여 Xplenty의 Rest API를 호출 해 보겠습니다. 

1. Rest API의 URL을 주소창에 설정
2. 위의 URL에 대해 적절한 메서드(여기서는 GET)를 선택합니다.
3. 인증(Authentication)에서 방법을 Basic으로 선택한 후, username에는 API_KEY를 입력하고 password는 비워둔다.
   
4. Header에 호출 시 필요한 Header를 해당 API의 문서를 참고하여 적절히 설정한다.
   
5. Send 버튼을 눌러 응답을 확인한다.
   

Curl 명령어로 호출하기

커맨드 라인에 의한 조작에 익숙한 분이라면 curl 명령어를 잘 사용하고 있을것으로 생각합니다.
curl의 조작 방법이 궁금하다면 아래 두 가지 자료를 참고하면 좋을 것 같다.

• curl tutorial(영어)
• 간이 가이드(한국어)

앞의 Postman과 동일한 조작을 curl 명령어로 실행합니다.
호출 시 필요한 정보는 아래의 옵션을 사용하여 설정해 주시면 됩니다.

1. -X : 메서드 지정(GET 지정)
2. -u : Baisc 인증 설정(<API_KYE>:)
3. URL : 작업 목록 조회를 위한 REST API의 URL
4. -H : Rest API 호출 시 필요한 헤더 정보

• 요청 (Curl Call)

   curl -X GET -u <API_KEY>: “https://api.xplenty.com/<account_id>/api/jobs” \
    -H “Accept: application/vnd.xplenty+json; version=2” 

• 응답

  [
    {
      "id": 304,
      "status": "failed",
      "variables":
      {
          "InputPath": "'/today'"
      },
      "owner_id": 1,
      "progress": 0,
      "outputs_count": 0,
      "outputs": [],
      "started_at": "2013-03-04T08:02:20Z",
      "created_at": "2013-03-04T08:02:17Z",
      "updated_at": "2013-03-04T08:03:01Z",
      "failed_at": null,
      "cluster_id": 176,
      "package_id": 103,
      "errors": "Package failed to execute.",
      "runtime_in_seconds": 40,
      "completed_at": "2013-03-04T08:03:01Z",
      "url": "https://api.xplenty.com/xplenation/api/jobs/304",
      "html_url": "https://xplenty.com/xplenation/jobs/304",
      "log_url": "https://api.xplenty.com/xplenation/api/jobs/304/log",
      "creator":
      {
          "type":"Schedule",
          "id":1,
          "display_name": "Schedule 1",
          "url": "https://api.xplenty.com/xplenation/api/schedules/1",
          "html_url": "https://xplenty.com/xplenation/schedules/1"
      },
      "package": {
        "id": 2373,
        "name": "AWS CloudFront Log Analysis",
        "description": "This package processes AWS CloudFront logs and extracts traffic information by time, geography and URIs",
        "variables": {},
        "owner_id": 8,
        "created_at": "2014-03-12T07:09:18Z",
        "updated_at": "2014-04-13T19:38:04Z",
        "url": "https://api.xplenty.com/xplenation/api/packages/2373",
        "status":"active"
      },
      "cluster": {
         "id": 99,
        "name": "Daily Outliers Test #100",
        "description": "Daily Outliers Test",
           :
           :
        "bootstrap_actions": [{
          "script_path": "http://xplenty.s3.amazonaws.com/bootstrap-actions/file1.tar.gz",
          "args": ["arg1", "arg2"]
        }, {
          "script_path": "http://xplenty.s3.amazonaws.com/bootstrap-actions/file1.tar.gz",
          "args": ["arg1"]
        }],
        "creator":
        {
            "type":"Schedule",
            "id":1,
            "display_name": "Schedule 1",
            "url": "https://api.xplenty.com/xplenation/api/schedules/1",
            "html_url": "https://xplenty.com/xplenation/schedules/1"
        }
      }
    },
    {
          :
          :
    },
    {
          :
          :
    }
  ]

Xplenty 리소스 보기

Xplenty에는 데이터 전송 작업과 관련된 몇 가지 개념을 리소스라고 부릅니다. 작업에 해당하는 적절한 리소스를 선택하여 조작을 수행합니다.
열람용의 Rest API는 이러한 리소스의 존재 여부 및 리소스의 상세 정보를 얻기 위해 필수적인 API이며, Rest API에서 열람용은 각 리소스에 대해 GET 메소드를 통해 호출 됩니다.

Xplenty의 주요 리소스 소개

Xplenty에서 사용되는 주요 리소스는 아래와 같습니다.

주요 리소스 열람 API

주요 리소스를 조회하기 위해 아래의 API를 사용합니다. 각각의 Rest API에는 지정 가능한 파라미터가 존재하며, 해당 파라미터의 지정에 따라 조회 범위의 제한 또는 가능 여부가 결정됩니다. 자세한 내용은 해당 링크를 참고하시기 바랍니다. 또한, 아래의 Rest API는 인증된 사용자에게만 허용됩니다.

조회 API의 주요 쿼리 파라미터

GET 메서드로 리소스를 가져오는 브라우징 API는 리소스의 범위를 지정하는 몇 가지 쿼리 파라미터가 있습니다. 자세한 내용은 바로 위의 열람 API를 참고하기 바라며, 주로 사용하는 파라미터는 다음과 같다.

열람 시 제한 사항(offset과 limit)

Xpelnty의 열람 API는 시스템의 영향을 고려하여 반환 목록의 임계값을 설정하고 있다. 임계값과 관련된 파라미터로 offset과 limit이 있습니다.
두 파라미터를 지정하지 않고 열람 API를 호출하면, 기본적으로 offset = 0과 limit = 20이 열람용 API에 부여됩니다.
또한 limit의 최대값은 100까지 지정할 수 있으므로, 열람용 Rest API를 사용할 때 offset과 limit의 적절한 값 조정을 권장합니다.

마치며

이상으로 Xplenty가 제공하는 Rest API 중 열람계에 대해 알아보았다. 다음에는 Rest API를 사용하여 Xplenty로 데이터를 전송하는 방법을 살펴보겠습니다.
Xplenty는 IT 백그라운드가 없는 사람뿐만 아니라 IT에 익숙한 사람들도 편리하게 사용할 수 있는 유연한 환경을 제공하고 있습니다.

2주간 무료 트라이얼을 통해 Xplenty의 편리함을 직접 경험해 보시기 바랍니다.
진심으로 기다리고 있습니다.