DPF-APIリファレンスマニュアル (1.0)

Download OpenAPI specification:Download

1. はじめに

1.1 DPF-APIについて

IIJ DNSプラットフォームサービスでは、DNSレコードやゾーン情報などを、
お客様が用意したプログラムから自動的に操作するためのAPI機能を提供しています。
以降、IIJ DNSプラットフォームサービスを「DPF」、DPFが提供するAPIを「DPF-API」あるいは単に「API」と表記します。
DPF-APIの利用には、DPFの契約とIIJ IDサービスの契約が必要となります。

本リファレンスマニュアルはOpenAPIに準拠しています。

1.2 サポート範囲

DPF-APIを呼び出すためのプログラム、及びそのプログラムを稼働させるためのサーバは、お客様にてご用意ください。
お客様にご用意いただくプログラムの開発、利用、動作についてのお問い合わせは承ることができません。

以下の事項についてのお問い合わせは、弊社サポートセンターにて承ります。

  • DPF-APIの挙動が本リファレンスマニュアルと異なる場合
  • DPF-APIがシステムエラーを応答した場合

1.3 参考資料

2. 利用方法

DPF-APIは、URLとHTTPリクエストヘッダ、HTTPリクエストボディでパラメータを指定して利用します。
また、IIJ IDサービスのアクセストークンと管理対象の権限設定が必要です。

2.1 リクエスト仕様

項目 規格
プロトコル HTTP/1.1、HTTP/2(https)
HTTPメソッド GET、POST、PATCH、PUT、DELETE
フォーマット JSON
文字コード UTF-8
タイムアウト 300秒
  • httpでのリクエストは受け付けません。必ずhttpsを使用してください。
  • DPF-APIを呼び出すプログラムは、リクエスト先が正当なものであることを確認するため、SSL証明書を検証することを推奨します。
  • 短期間に極めて多数のリクエストが行われた場合、サービスの健全性を保つためにリクエストを制限する場合があります。

アクセストークン

APIリクエストの際にIIJ IDサービスによって発行されたアクセストークンをAuthorizationヘッダに指定する必要があります。
各APIにより必要となるアクセス権の範囲(許可するスコープ)が異なるのでご注意ください。

アクセストークン作成時に指定できる「許可するスコープ」は以下のとおりです。

許可するスコープ 実行できるAPI
dpf_read 参照系API
dpf_write 更新系、及び参照系API
dpf_contract 契約系API

発行済のアクセストークンは、IIJ IDサービスの「アクセストークンの管理」より確認できます。
DPF-APIを利用する場合は「利用するリソースサーバ」の設定で「IIJ DNSサービスAPI」を選択してください。
アクセストークン管理方法のマニュアルはこちらを参照してください。

管理対象の権限設定

DPFでは、管理対象となる契約単位での参照、編集権限を細かく設定できます。
アクセストークンの許可するスコープが適切であっても、管理対象の権限が付与されていない場合はAPIを実行できません。
管理対象の権限設定のマニュアルはこちらを参照してください。

2.2 HTTPリクエスト

<HTTPメソッド> /dpf/<version>/<APIパス> HTTP/1.1
Host: api.dns-platform.jp
Authorization: Bearer <access_token>
Content-Type: application/json; charset=UTF-8

<HTTPリクエストボディ: JSON形式のAPI固有のパラメータ>

リクエストパラメータ

DPF-APIで指定するパラメータは以下のとおりです。
リクエストパラメータに同一のキーが含まれる場合の動作は保証されません。

共通 指定箇所 パラメータ 意味
共通 HTTPメソッド HTTPメソッド HTTPメソッド(値:GET、POST、PATCH、PUT、DELETE)
共通 URL version DPF-APIバージョン(値:v1)
個別 URL APIパス API名称やAPI個別のパラメータの組み合わせ(参照:API一覧
共通 HTTPヘッダー access_token IIJ IDアクセストークン(参照:IIJ IDサービス
個別 HTTPボディ APIごとに異なる JSON形式のパラメータ(参照:API一覧

2.3 HTTPレスポンス

成功レスポンス

APIごとにレスポンスが異なりますので、該当のAPIを参照してください。

エラーレスポンス

HTTPステータスコード、及びレスポンスボディによってクライアントプログラムにエラーを通知します。

例:アクセストークンが誤っている

{
  "request_id": "782d746ac3cb46499b31708fa80e8660",
  "error_type": "ParameterError",
  "error_message": "There are invalid parameters.",
  "error_details": [
    {
      "code": "invalid",
      "attribute": "access_token"
    }
  ]
}

エラーコード一覧

HTTP Status Code error_type error_message code attribute 説明 対処方法
400 ParameterError There are invalid parameters. invalid access_token 指定したアクセストークンに誤りがあります アクセストークンを確認してください
400 ParameterError JSON parse error occurred. - - パラメータとして不正なJSON文字列が指定されました リクエストのパラメータを確認してください
400 ParameterError There are invalid parameters. (API個別) (API個別) 不正なパラメータが指定されました 各APIのエラーコードを確認してください
404 NotFound Specified resource not found. - - アクセスURLが正しくありません
存在しないAPIが指定されました
指定された以外のHTTPメソッドが指定されました
左記の内容を確認してください
429 TooManyRequests Too many requests. - - 大量のAPIリクエストが送信されました 単位時間当たりのAPIリクエスト数を確認してください
500 SystemError System error occurred. - - システム障害が発生しました サポートセンターへお問い合わせください
504 GatewayTimeout Gateway timeout. - - リクエストがタイムアウトしました しばらく待ってから再度リクエストしてください

2.4 非同期リクエスト

DPF-APIにおけるGET以外のAPIは全て非同期APIです。
非同期APIはリクエストを受け付けると即座にレスポンスを返却しますが、
リクエストに対する実際の処理は非同期で行われます。

非同期リクエストの受け付けに成功した場合のHTTPステータスコードは202で、
返却されたレスポンスボディには、処理進捗を確認するためのURL(jobs_url)が含まれます。
このjobs_urlに対してGETリクエストをすることで進捗状況を確認できます。

進捗状況を確認した際、非同期処理が正常に終了していた場合は、
返却されたレスポンスボディには、対象リソースを取得するためのURL(resources_url)が含まれます。
このresources_urlに対してGETリクエストをすることで実行結果を確認できます。

非同期リクエストのレスポンス

HTTP/1.1 202 Accepted
Date: Mon, 26 Mar 20XX hh:mm:dd GMT
Content-Type: application/json; charset=utf-8
〜 略 〜

{
  "request_id": "782d746ac3cb46499b31708fa80e8660",
  "jobs_url": "https://api.dns-platform.jp/dpf/<version>/jobs/<request_id>"
}

GETリクエスト

GET /dpf/<version>/jobs/<request_id> HTTP/1.1
Host: api.dns-platform.jp
Authorization: Bearer <access_token>
Content-Type: application/json; charset=UTF-8

{}

進捗状況のレスポンス

HTTP/1.1 200 OK
Date: Mon, 26 Mar 20XX hh:mm:dd GMT
Content-Type: application/json; charset=utf-8
〜 略 〜

{
  "request_id": "782d746ac3cb46499b31708fa80e8660",
  "resources_url": <resources_url>,
  "status": "SUCCESSFUL"
}

3. API一覧

DPF-APIではIIJ DNSプラットフォームサービスに関する以下の操作を行うことができます。

3.1 IIJ DNSプラットフォームサービス

cc_notice_accounts

HTTPメソッド API 機能 許可するスコープ
GET /common_configs/{CommonConfigId}/cc_notice_accounts 通知先アカウント設定の一覧取得 dpf_read
POST /common_configs/{CommonConfigId}/cc_notice_accounts 通知先アカウント設定の作成 dpf_write
GET /common_configs/{CommonConfigId}/cc_notice_accounts/{CcNoticeAccountResourceName} 通知先アカウント設定の取得 dpf_read
PATCH /common_configs/{CommonConfigId}/cc_notice_accounts/{CcNoticeAccountResourceName} 通知先アカウント設定の更新 dpf_write
DELETE /common_configs/{CommonConfigId}/cc_notice_accounts/{CcNoticeAccountResourceName} 通知先アカウント設定の削除 dpf_write

cc_primaries

HTTPメソッド API 機能 許可するスコープ
GET /common_configs/{CommonConfigId}/cc_primaries プライマリネームサーバ設定の一覧取得 dpf_read
POST /common_configs/{CommonConfigId}/cc_primaries プライマリネームサーバ設定の作成 dpf_write
GET /common_configs/{CommonConfigId}/cc_primaries/{CcPrimaryId} プライマリネームサーバ設定の取得 dpf_read
PATCH /common_configs/{CommonConfigId}/cc_primaries/{CcPrimaryId} プライマリネームサーバ設定の更新 dpf_write
DELETE /common_configs/{CommonConfigId}/cc_primaries/{CcPrimaryId} プライマリネームサーバ設定の削除 dpf_write

cc_sec_notified_servers

HTTPメソッド API 機能 許可するスコープ
GET /common_configs/{CommonConfigId}/cc_sec_notified_servers DNS NOTIFY設定の一覧取得 dpf_read
POST /common_configs/{CommonConfigId}/cc_sec_notified_servers DNS NOTIFY設定の作成 dpf_write
GET /common_configs/{CommonConfigId}/cc_sec_notified_servers/{CcSecNotifiedServerId} DNS NOTIFY設定の取得 dpf_read
PATCH /common_configs/{CommonConfigId}/cc_sec_notified_servers/{CcSecNotifiedServerId} DNS NOTIFY設定の更新 dpf_write
DELETE /common_configs/{CommonConfigId}/cc_sec_notified_servers/{CcSecNotifiedServerId} DNS NOTIFY設定の削除 dpf_write

cc_sec_transfer_acls

HTTPメソッド API 機能 許可するスコープ
GET /common_configs/{CommonConfigId}/cc_sec_transfer_acls ゾーン転送ACLの一覧取得 dpf_read
POST /common_configs/{CommonConfigId}/cc_sec_transfer_acls ゾーン転送ACLの作成 dpf_write
GET /common_configs/{CommonConfigId}/cc_sec_transfer_acls/{CcSecTransferAclId} ゾーン転送ACLの取得 dpf_read
PATCH <