API実装について

APIバージョン

このドキュメントでは、APIのバージョン1について説明します。すべてのリクエストは、/api/1/から始まるパスに移動します。

API認証

Uptrack APIサーバーへの認証では、カスタムHTTPヘッダーで指定されているユーザー名およびAPIキーを使用します。すべてのリクエストには、リクエストを作成するユーザーのAPIユーザー名およびAPIキーを含めたX-Uptrack-UserおよびX-Uptrack-Key HTTPヘッダーが含まれている必要があります。

APIリクエスト形式

APIリクエストまたはレスポンスには、JSONエンコード・データがリクエスト本体に含まれます。すべてのリクエストにapplication/jsonのContent-Typeヘッダーを設定します。同様に、コンテンツを含むレスポンスが予期されるリクエストには、値application/jsonを指定したAccept:ヘッダーを含めます。

APIはJSONエンコード・データのみを使用するため、これらのヘッダーは必要ありませんが、将来のバージョンのAPIで他のデータ・エンコード形式が使用される可能性があります。

使用可能なAPIリクエスト

使用可能なAPIリクエストの説明を次に示します。

GET /api/1/machines

GET /api/1/machines APIリクエストは、登録されているすべてのシステムのリストを返します。このリストには、Uptrackをアンインストールした非アクティブなシステムやUptrackサーバーに最近レポートされていないシステムが含まれています。リストには、Webインタフェースを使用して非表示にしたシステムは含まれません。レスポンスには、システムのリストが表示されます。システムは、次の例に示すように、ディクショナリとして表されます。

 {
      hostname: uptrack.example.com,
      ip: 184.73.248.238,
      last_seen: '2010-04-26T18:03:43Z',
      uuid: e82ba0ae-ad0a-4b92-a776-62b502bfd29d,
      active: true,
      status: uptodate,
      authorization: allowed,
      autoinstall: true,
      mmap_min_addr: 4096,
      uptrack_client_version: 1.2.1
   }

レスポンスには次のフィールドがあります。

status

次の値のいずれかが含まれています。

outofdate - システムにインストールするために更新を使用できます。
unsupported - システムのカーネルがKsplice Uptrackでサポートされていません。
uptodate - 使用可能なすべての更新がシステムにインストールされています。

authorization

次の値のいずれかが含まれています。

allowed - システムは、Uptrackサーバーと通信して更新を受信できます。
denied - システムは、Webインタフェース、uptrack-api-authorizeまたはauthorize APIコールを使用したUptrackサーバーへのアクセスが拒否されています。
pending - このアカウントには、新しいシステムに対するデフォルトの拒否ポリシー・セットがあり、システムはまだ認可されていません。

autoinstall

システムにautoinstallが設定されているかどうかを示します。

mmap_min_addr

/proc/sys/vm/mmap_min_addrの値です。バージョン1.0.3より前のクライアントの場合はNoneです。

uptrack_client_version

システムが実行されているUptrackクライアントのバージョンです。

GET /api/1/machine/$UUID/describe

GET /api/1/machine/$UUID/describe APIリクエストは、指定したUUIDのシステムに関する情報を返します。システムのUUIDは、/var/lib/uptrack/uuidに保存されており、machines問合せを使用して取得できます。レスポンスは、次のフィールドを含む点を除き、GET /api/1/machinesが返すのと同じ形式のディクショナリです:

effective_kernel: Kspliceは、システムとこのカーネル・バージョンを一致させるのに必要とされる、重要なセキュリティおよび信頼性に関するすべての更新を適用しました。
group: システムが割り当てられているグループ。Webインタフェースを使用してシステムのグループを管理することもできます。
installed_updates: システムにインストールされている更新を表す、{'ID': update_id, 'Name': update_name}という形式の2要素ディクショナリのリスト。update_idは、更新のIDコード(例: diptbg4f)、update_nameは、更新の短い説明的な名前(例: CVE-2010-0415: Information Leak in sys_move_pages)です。
original_kernel: Ksplice更新が適用される前のシステムのカーネル・バージョン。
steps: [action, {'ID': update_id, 'Name': update_name}]という形式の2つの要素リストのリストで、システムを更新するためにインストールまたは削除する必要がある更新を表します。action引数には、InstallまたはRemoveを指定できます。既存の更新は新しいバージョンで置き換えられた場合には削除されることに注意してください。

POST /api/1/machine/$UUID/authorize

POST /api/1/machine/$UUID/authorize APIリクエストは、新しいシステムへのアクセスを拒否するようにアカウントを構成している場合、Uptrackサービスにアクセスできるように、指定したUUIDのシステムを認可します。

ディクショナリのコンテンツの形式は次のとおりです。

{authorized: boolean}

boolean引数をtrue (システムを認可する)またはfalse (認可を取り消す)に指定します。

POST /api/1/machine/$UUID/group

POST /api/1/machine/$UUID/group APIリクエストは、指定したUUIDのシステムのグループを変更します。

コンテンツは、次の形式を使用するディクショナリです。

{group_name: string}

前の例では、stringは新しいグループの名前です。グループがまだ存在していない場合は、作成されます。指定したUUIDのシステムがアカウントに存在しない場合、リクエストはHTTP 404エラーになります。

システムをグループから削除する場合は、グループを別の名前に設定するか、グループなしの空の文字列を指定できます。

サンプルの対話

次の例は、参考のためにのみ提供されており、Uptrack APIの使用時に行われる可能性がある対話を示しています。

この対話は、Secure Sockets Layer (SSL)プロトコルを使用してポート443を経由するサーバーuptrack.api.ksplice.comで行われます。

サーバーに対して登録済システムのリストをリクエストする例を次に示します:

GET /api/1/machines HTTP/1.1
Host: uptrack.api.ksplice.com
Accept: application/json
X-Uptrack-User: jo.admin@example.com
X-Uptrack-Key: 3af3c2c1ec407feb0fdc9fc1d8c4460c

サーバーは、リクエストを認証して、次のようにシステムのリストで応答します:

HTTP/1.0 200 OK
Date: Mon, 03 May 2010 21:09:48 GMT
Content-Type: application/json

[{"status": "uptodate", "uuid": "e82ba0ae-ad0a-4b92-a776-62b502bfd29d",
  "active": true, "ip": "192.168.248.238", "hostname": "utclient.example.com",
  "authorization": "allowed", "autoinstall": true,
  "last_seen": "2010-04-26T18:03:43Z", "mmap_min_addr": 4096,
  "uptrack_client_version": "1.2.1"}]