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

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

このWEBページはopenapi.jsonから自動生成しています。このWEBページとopenapi.jsonの内容が異なる場合は、openapi.jsonの内容を正とします。 openapi.jsonは、上部のDownloadボタンからダウンロードできます。

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

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

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

• IIJ DNSプラットフォームサービス オンラインマニュアル

  • https://manual.iij.jp/dpf/help/

• IIJ IDサービス オンラインマニュアル

  • https://manual.iij.jp/iid/admin-help/

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

• httpでのリクエストは受け付けません。必ずhttpsを使用してください。
• DPF-APIを呼び出すプログラムは、リクエスト先が正当なものであることを確認するため、SSL証明書を検証することを推奨します。
• 短期間に極めて多数のリクエストが行われた場合、サービスの健全性を保つためにリクエストを制限する場合があります。

アクセストークン

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

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

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

管理対象の権限設定

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

例

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

成功レスポンス

APIごとにレスポンスが異なります。

エラーレスポンス

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

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

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

エラーコード一覧

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 202X hh:mm:dd GMT
Content-Type: application/json; charset=utf-8
〜 略 〜

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

通知先アカウントの操作ができます。

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

enabled

DNS NOTIFYの操作ができます。

ゾーン転送ACLの操作ができます。

複数のゾーンおよびLBドメインで共通の設定内容を使用するための共通設定を操作できます。
マネージドDNSサーバの状態（managed_dns_enabled）、初期適用の共通設定（default）は以下のとおりです。

managed_dns_enabled

default

DPF契約の操作ができます。
契約プラン（plan）、契約の状態（state）、お気に入りの状態（favorite）は以下のとおりです。

plan

state

favorite