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

Download OpenAPI specification:Download

はじめに

DPF-APIについて

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

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

サポート範囲

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

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

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

参考資料

利用方法

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

リクエスト仕様

項目 規格
プロトコル HTTP/1.1、HTTP/2(https)
HTTPメソッド GET、PATCH、POST、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を実行できません。
管理対象の権限設定のマニュアルはこちらを参照してください。

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、PATCH、POST、DELETE)
共通 URL version DPF-APIバージョン(値:v1)
個別 URL APIパス API名称やAPI個別のパラメータの組み合わせ(参照:API一覧
共通 HTTPヘッダー access_token IIJ IDアクセストークン(参照:IIJ IDサービス
個別 HTTPボディ APIごとに異なる JSON形式のパラメータ(参照:API一覧

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. access_token invalid 指定したアクセストークンに誤りがあります アクセストークンを確認してください
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. - - リクエストがタイムアウトしました しばらく待ってから再度リクエストしてください

非同期リクエスト

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"
}

API一覧

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

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

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 /common_configs/{CommonConfigId}/cc_sec_transfer_acls/{CcSecTransferAclId} ゾーン転送ACLの更新 dpf_write
DELETE /common_configs/{CommonConfigId}/cc_sec_transfer_acls/{CcSecTransferAclId} ゾーン転送ACLの削除 dpf_write

common_configs

HTTPメソッド API 機能 許可するスコープ
GET /contracts/{ContractId}/common_configs 共通設定の一覧取得 dpf_read
POST /contracts/{ContractId}/common_configs 共通設定の作成 dpf_write
GET /contracts/{ContractId}/common_configs/count 共通設定の件数取得 dpf_read
PATCH /contracts/{ContractId}/common_configs/default 初期適用される共通設定の更新 dpf_write
GET /contracts/{ContractId}/common_configs/{CommonConfigId} 共通設定の取得 dpf_read
PATCH /contracts/{ContractId}/common_configs/{CommonConfigId} 共通設定の更新 dpf_write
DELETE /contracts/{ContractId}/common_configs/{CommonConfigId} 共通設定の削除 dpf_write
POST /contracts/{ContractId}/common_configs/{CommonConfigId}/copy 共通設定のコピー dpf_write
PATCH /contracts/{ContractId}/common_configs/{CommonConfigId}/managed_dns マネージドDNSサーバの状態更新 dpf_write

contracts

HTTPメソッド API 機能 許可するスコープ
GET /contracts DPF契約情報の一覧取得 dpf_read
GET /contracts/count DPF契約情報の件数取得 dpf_read
GET /contracts/{ContractId} DPF契約情報の取得 dpf_read
PATCH /contracts/{ContractId} DPF契約情報の更新 dpf_write

contract_partners

HTTPメソッド API 機能 許可するスコープ
GET /contracts/{ContractId}/contract_partners DPF連携サービスの一覧取得 dpf_read

logs (contracts)

HTTPメソッド API 機能 許可するスコープ
GET /contracts/{ContractId}/logs DPF契約操作ログの一覧取得 dpf_read
GET /contracts/{ContractId}/logs/count DPF契約操作ログの件数取得 dpf_read

qps

HTTPメソッド API 機能 許可するスコープ
GET /contracts/{ContractId}/qps/histories 月別のQPSの一覧取得 dpf_read

tsigs

HTTPメソッド API 機能 許可するスコープ
GET /contracts/{ContractId}/tsigs TSIG鍵の一覧取得 dpf_read
POST /contracts/{ContractId}/tsigs TSIG鍵の作成 dpf_write
GET /contracts/{ContractId}/tsigs/count TSIG鍵の件数取得 dpf_read
GET /contracts/{ContractId}/tsigs/{TsigId} TSIG鍵の取得 dpf_read
PATCH /contracts/{ContractId}/tsigs/{TsigId} TSIG鍵の更新 dpf_write
DELETE /contracts/{ContractId}/tsigs/{TsigId} TSIG鍵の削除 dpf_write
GET /contracts/{ContractId}/tsigs/{TsigId}/common_configs TSIG鍵を利用している共通設定の一覧取得 dpf_read
GET /contracts/{ContractId}/tsigs/{TsigId}/common_configs/count TSIG鍵を利用している共通設定の件数取得 dpf_read

zones (contracts)

HTTPメソッド API 機能 許可するスコープ
GET /contracts/{ContractId}/zones DPF契約に紐付くゾーンの一覧取得 dpf_read
PATCH /contracts/{ContractId}/zones/common_configs DPF契約に紐付くゾーンの共通設定の更新 dpf_write
GET /contracts/{ContractId}/zones/count DPF契約に紐付くゾーンの件数取得 dpf_read

IIJマネージドDNSサービス

default_ttl

HTTPメソッド API 機能 許可するスコープ
GET /zones/{ZoneId}/default_ttl デフォルトTTLの取得 dpf_read
PATCH /zones/{ZoneId}/default_ttl デフォルトTTLの更新 dpf_write
DELETE /zones/{ZoneId}/default_ttl/changes 編集中デフォルトTTLの取消 dpf_write
GET /zones/{ZoneId}/default_ttl/diffs デフォルトTTLの編集差分の取得 dpf_read

dnssec

HTTPメソッド API 機能 許可するスコープ
GET /zones/{ZoneId}/dnssec DNSSEC情報の取得 dpf_read
PATCH /zones/{ZoneId}/dnssec DNSSEC情報の更新 dpf_write
PATCH /zones/{ZoneId}/dnssec/ksk_rollover KSKロールオーバーの開始 dpf_write

ds_records

HTTPメソッド API 機能 許可するスコープ
GET /zones/{ZoneId}/ds_records DSレコードの一覧取得 dpf_read

logs (zones)

HTTPメソッド API 機能 許可するスコープ
GET /zones/{ZoneId}/logs ゾーン操作ログの一覧取得 dpf_read
GET /zones/{ZoneId}/logs/count ゾーン操作ログの件数取得 dpf_read

records

HTTPメソッド API 機能 許可するスコープ
GET /zones/{ZoneId}/records レコードの一覧取得 dpf_read
POST /zones/{ZoneId}/records レコードの作成 dpf_write
GET /zones/{ZoneId}/records/count レコードの件数取得 dpf_read
GET /zones/{ZoneId}/records/currents DNS反映済レコードの一覧取得 dpf_read
GET /zones/{ZoneId}/records/currents/count DNS反映済レコードの件数取得 dpf_read
GET /zones/{ZoneId}/records/diffs レコードの編集差分の一覧取得 dpf_read
GET /zones/{ZoneId}/records/diffs/count レコードの編集差分の件数取得 dpf_read
GET /zones/{ZoneId}/records/{RecordId} レコードの取得 dpf_read
PATCH /zones/{ZoneId}/records/{RecordId} レコードの更新 dpf_write
DELETE /zones/{ZoneId}/records/{RecordId} レコードの削除 dpf_write
DELETE /zones/{ZoneId}/records/{RecordId}/changes 編集中レコードの取消 dpf_write

zone_histories

HTTPメソッド API 機能 許可するスコープ
GET /zones/{ZoneId}/zone_histories ゾーン反映履歴の一覧取得 dpf_read
GET /zones/{ZoneId}/zone_histories/count ゾーン反映履歴の件数取得 dpf_read
GET /zones/{ZoneId}/zone_histories/{ZoneHistoryId}/text ゾーン反映時のRFC1035形式のテキストの取得 dpf_read

zone_proxy

HTTPメソッド API 機能 許可するスコープ
GET /zones/{ZoneId}/zone_proxy ゾーンプロキシ設定の取得 dpf_read
PATCH /zones/{ZoneId}/zone_proxy ゾーンプロキシ設定の更新 dpf_write
GET /zones/{ZoneId}/zone_proxy/health_check プライマリネームサーバのヘルスチェック結果の取得 dpf_read

zones

HTTPメソッド API 機能 許可するスコープ
GET /zones ゾーンの一覧取得 dpf_read
GET /zones/count ゾーンの件数取得 dpf_read
GET /zones/{ZoneId} ゾーンの取得 dpf_read
PATCH /zones/{ZoneId} ゾーンの更新 dpf_write
PATCH /zones/{ZoneId}/changes 編集中レコードのゾーン反映 dpf_write
DELETE /zones/{ZoneId}/changes 編集中レコードの一括取消 dpf_write
GET /zones/{ZoneId}/contract ゾーンに紐付くDPF契約情報の取得 dpf_read
GET /zones/{ZoneId}/managed_dns_servers マネージドDNSサーバの一覧取得 dpf_read

サービス共通

delegations

HTTPメソッド API 機能 許可するスコープ
GET /delegations ネームサーバ申請候補の一覧取得 dpf_read
POST /delegations ネームサーバ申請 dpf_write
GET /delegations/count ネームサーバ申請候補の件数取得 dpf_read

jobs

HTTPメソッド API 機能 許可するスコープ
GET /jobs/{RequestId} 非同期リクエストの状態確認 dpf_read

ping

HTTPメソッド API 機能 許可するスコープ
GET /ping API疎通確認 dpf_read, dpf_write, dpf_contract

cc_primaries

プライマリネームサーバの操作ができます。
プライマリネームサーバの状態(enabled)は以下のとおりです。

enabled

意味 備考
0 無効
1 有効

プライマリネームサーバ設定の一覧取得

プライマリネームサーバの設定の一覧を取得します。

Authorizations

dpf_read

path Parameters
CommonConfigId
required
integer <int64> (Id) >= 1

ID

Responses

200

OK

400

Bad Request

ErrorDetails
code attribute 対処方法
not_found common_config 指定したCommonConfigIdを確認してください
invalid schema 指定したパラメータを確認してください
get /common_configs/{CommonConfigId}/cc_primaries

API endpoint

https://api.dns-platform.jp/dpf/v1/common_configs/{CommonConfigId}/cc_primaries

Response samples