IIJ xSPプラットフォームサービス/キャッシュDNS APIリファレンス (2.0.0)

Download OpenAPI specification:Download

1. はじめに

1.1 本文書について

本文書は、IIJ xSPプラットフォームサービス/キャッシュDNSのユーザ用のAPI(以下XDNS-API)を定義しています。本文書は、OpenAPIに準拠しています。

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

1.2 サポート範囲

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

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

XDNS-APIの挙動が本リファレンスマニュアルと異なる場合
XDNS-APIがシステムエラーを応答した場合サポートセンターの問い合わせ先については、サービスオンラインのご利用の手引きをご覧ください。

2. 利用方法

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

2.1 リクエスト仕様

項目	規格
プロトコル	HTTP/1.1、HTTP/2（https）
HTTPメソッド	GET、POST、PUT
フォーマット	JSON
文字コード	UTF-8
タイムアウト	300秒

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

アクセストークン

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

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

許可するスコープ	実行できるAPI
xdns_read	参照系API
xdns_write	参照系API, 更新系API

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

管理対象の権限設定

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

2.2 HTTPリクエスト

参照系APIの例

GET /<version>/<APIパス> HTTP/1.1
Host: api.xsp-dns.iij.jp
Authorization: Bearer <access_token>

更新系APIの例

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

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

リクエストパラメータ

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

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

契約情報

契約情報を取得する

CNS情報を返すAPIです。
IPアドレス情報と、DoHのホスト名情報を返します。

Authorizations:

ConfigurationViewerConfigurationOperatorConfigurationOperator

path Parameters

service_code

required

string (ServiceCode) = 11 characters

Example: xpd00000000

サービスコード

Responses

Response samples

200
400
403
500

Content type

application/json

{"request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
"service_code": "xpd00000000",
"result": {"kind": "Contract",
"service_code": "xpd00000000",
"metadata": {"labels": {"description": "絵文字も利用可能🍺",
"name": "for west Japan"
}
},
"state": "RUNNING",
"dns_ips": {"id": 1,
"ns0_ipv4": "203.0.113.1",
"ns0_ipv6": "2001:db8::1",
"ns1_ipv4": "203.0.113.2",
"ns1_ipv6": "2001:db8::2"
},
"doh_names": ["example.xsp-dns.jp."
]
}
}

契約情報のメタデータを設定する

契約情報のメタ情報を設定するAPIです。
Labelを付与できます。

Authorizations:

ConfigurationOperator

path Parameters

service_code

required

string (ServiceCode) = 11 characters

Example: xpd00000000

サービスコード

Request Body schema: application/json

required	object
kind required	string Value: "ContractMetadata"

Responses

Request samples

Payload

Content type

application/json

{"labels": {"description": "絵文字も利用可能🍺",
"name": "for west Japan",
"example.jp/hoge": "ドメイン部＋ラベル部のkey",
"example_code": "hogehoge",
"example.jp/Code_Red": "false"
},
"kind": "ContractMetadata"
}

Response samples

200
208
400
403
500

Content type

application/json

{"request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
"service_code": "xpd00000000"
}

API ACL

APIが利用可能なネットワークを取得

APIが利用可能なネットワークを取得するAPIです。
ネットワークが空の場合は、全てのネットワークからAPIの利用ができます。
ネットワークの初期状態は空です。

Authorizations:

ConfigurationViewerConfigurationOperatorConfigurationOperator

path Parameters

service_code

required

string (ServiceCode) = 11 characters

Example: xpd00000000

サービスコード

Responses

Response samples

200
400
403
500

Content type

application/json

{"request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
"service_code": "xpd00000000",
"result": {"kind": "APIACL",
"networks": ["2001:db8::/48",
"203.0.113.0/24"
]
}
}

APIが利用可能なネットワークを設定

APIが利用可能なネットワークを設定するAPIです。
空のネットワークをセットした場合、全てのネットワークからAPIの利用ができるようになります。
IPv6のネットワークは、RFC5952に従い、正規化されて処理します。
- 正規化した値を保存いたします。

Authorizations:

ConfigurationOperator

path Parameters

service_code

required

string (ServiceCode) = 11 characters

Example: xpd00000000

サービスコード

Request Body schema: application/json

kind required	string Value: "APIACL"
networks required	Array of strings (Networks) <= 10000 items unique ネットワークアドレスの集合 IPv6ネットワークアドレスは、RFC5952にしたがって正規化した後で判定全く同じネットワークアドレスの重複不可 192.168.0.0/24と192.168.0.0/24 2001:db8::/48と2001:0DB8:0000:0000::/48 レンジが重なる場合の重複は許可 192.168.0.0/16と192.168.1.0/24

Responses

Request samples

Payload

Content type

application/json

{"kind": "APIACL",
"networks": ["2001:db8::/48",
"203.0.113.0/24"
]
}

Response samples

200
208
400
403
500

Content type

application/json

{"request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
"service_code": "xpd00000000"
}

DNS ACL

DNSが利用可能なネットワークを取得

DNS(UDP,TCP)が利用可能なネットワークを取得するAPIです。
ネットワークが空の場合は、IIJの監視ネットワークを除く全てのネットワークから、DNS(UDP,TCP)の利用ができません。
ネットワークの初期状態は空です。

Authorizations:

ConfigurationViewerConfigurationOperatorConfigurationOperator

path Parameters

service_code

required

string (ServiceCode) = 11 characters

Example: xpd00000000

サービスコード

Responses

Response samples

200
400
403
500

Content type

application/json

{"request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
"service_code": "xpd00000000",
"result": {"kind": "DNSACL",
"networks": ["2001:db8::/48",
"203.0.113.0/24"
]
}
}

DNSが利用可能なネットワークのリストを設定

DNS(UDP,TCP)が利用可能なネットワークを設定するAPIです。
空のネットワークをセットした場合、IIJの監視ネットワークを除く全てのネットワークから、DNS(UDP,TCP)の利用ができなくなります。
IPv6のネットワークは、RFC5952に従い、正規化されて処理します。
- 正規化した値を保存いたします。
キャッシュDNSサーバへのACLの反映は、本APIでの変更後1時間以内に行われます。

Authorizations:

ConfigurationOperator

path Parameters

service_code

required

string (ServiceCode) = 11 characters

Example: xpd00000000

サービスコード

Request Body schema: application/json

kind required	string Value: "DNSACL"
networks required	Array of strings (Networks) <= 10000 items unique ネットワークアドレスの集合 IPv6ネットワークアドレスは、RFC5952にしたがって正規化した後で判定全く同じネットワークアドレスの重複不可 192.168.0.0/24と192.168.0.0/24 2001:db8::/48と2001:0DB8:0000:0000::/48 レンジが重なる場合の重複は許可 192.168.0.0/16と192.168.1.0/24

Responses

Request samples

Payload

Content type

application/json

{"kind": "DNSACL",
"networks": ["2001:db8::/48",
"203.0.113.0/24"
]
}

Response samples

200
208
400
403
500

Content type

application/json

{"request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
"service_code": "xpd00000000"
}

DoH ACL

DoHが利用可能なネットワークのリストを取得

HTTP(DoH)が利用可能なネットワークのリストを取得するAPIになります。
ネットワークが空の場合は、IIJの監視ネットワークを除く全てのネットワークから、アクセスできません。

Authorizations:

ConfigurationViewerConfigurationOperatorConfigurationOperator

path Parameters

service_code

required

string (ServiceCode) = 11 characters

Example: xpd00000000

サービスコード

Responses

Response samples

200
400
403
500

Content type

application/json

{"request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
"service_code": "xpd00000000",
"result": {"kind": "DoHACL",
"networks": ["2001:db8::/48",
"203.0.113.0/24"
]
}
}

DoHが利用可能なネットワークのリストを設定

DoHが利用可能なネットワークを設定するAPIです。
空のネットワークをセットした場合、IIJの監視ネットワークを除く全てのネットワークから、DoHの利用ができなくなります。
IPv6のネットワークは、RFC5952に従い、正規化されて処理します。
- 正規化した値を保存いたします。
キャッシュDNSサーバへのACLの反映は、本APIでの変更後1時間以内に行われます。

Authorizations:

ConfigurationOperator

path Parameters

service_code

required

string (ServiceCode) = 11 characters

Example: xpd00000000

サービスコード

Request Body schema: application/json

kind required	string Value: "DoHACL"
networks required	Array of strings (Networks) <= 10000 items unique ネットワークアドレスの集合 IPv6ネットワークアドレスは、RFC5952にしたがって正規化した後で判定全く同じネットワークアドレスの重複不可 192.168.0.0/24と192.168.0.0/24 2001:db8::/48と2001:0DB8:0000:0000::/48 レンジが重なる場合の重複は許可 192.168.0.0/16と192.168.1.0/24

Responses

Request samples

Payload

Content type

application/json

{"kind": "DoHACL",
"networks": ["2001:db8::/48",
"203.0.113.0/24"
]
}

Response samples

200
208
400
403
500

Content type

application/json

{"request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
"service_code": "xpd00000000"
}

DNS Filter

フィルタ機能の有効状態を取得

児童ポルノブロッキング機能、悪性ドメイン名フィルタリング機能の有効状態を取得するAPIです。

Authorizations:

ConfigurationViewerConfigurationOperatorConfigurationOperator

path Parameters

service_code

required

string (ServiceCode) = 11 characters

Example: xpd00000000

サービスコード

Responses

Response samples

200
400
403
500

Content type

application/json

{"request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
"service_code": "xpd00000000",
"result": {"kind": "DNSFilter",
"cpb_enabled": true,
"mdb_enabled": true
}
}

フィルタ機能を設定

児童ポルノブロッキング機能、悪性ドメイン名フィルタリング機能の有効状態を変更するAPIです。
ICSAへの加入が確認できていない場合、リクエストパラメータ内のcpb_enabledは無視されます。
- cpb_enabled=trueでリクエストした場合でも変更はされません。
- mdb_enabledに変更があった場合、そちらの変更は実施されます。
キャッシュDNSサーバへのフィルタ反映は、本APIでの変更後1時間以内に行われます。

Authorizations:

ConfigurationOperator

path Parameters

service_code

required

string (ServiceCode) = 11 characters

Example: xpd00000000

サービスコード

Request Body schema: application/json

kind required	string Value: "DNSFilter"
cpb_enabled required	boolean 児童ポルノブロッキング機能の有効状態
mdb_enabled required	boolean 悪性ドメイン名フィルタリング機能の有効状態

Responses

Request samples

Payload

Content type

application/json

{"kind": "DNSFilter",
"cpb_enabled": true,
"mdb_enabled": true
}

Response samples

200
208
400
403
500

Content type

application/json

{"request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
"service_code": "xpd00000000"
}

課金QPS

課金QPSの一覧取得

課金QPSを取得するAPIです。
最大で12ヶ月分の課金QPSを取得できます。
課金QPSは毎月1日から2日(JST)までの間に、前月分の月間の課金QPSが算出されます。
課金QPSの算出方法についてはマニュアルを参照ください。

Authorizations:

OperationViewerOperationOperatorOperationOperator

path Parameters

service_code

required

string (ServiceCode) = 11 characters

Example: xpd00000000

サービスコード

Responses

Response samples

200
400
403
500

Content type

application/json

{"request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
"service_code": "xpd00000000",
"result": {"kind": "QPS",
"values": [{"month": "2023-03-01",
"value": 443
},
{"month": "2023-02-01",
"value": 853
},
{"month": "2023-01-01",
"value": 53
}
]
}
}

Log

設定変更、操作ログの取得

設定系、キャッシュクリア系などのWrite操作の履歴を取得するAPIです。
最大90日前までのログまで取得できます。
1回のリクエストで、日時が新しいものから順に最大1000件のログが取得できます。
- ログが1000件を超える場合は、レスポンスに含まれるnext_page_tokenを付与してリクエストすることで、さらに古いログが取得できます。
ログとして記録される操作は、以下の条件を満たす必要があります。
- HTTPメソッドが、PUTまたはPOSTであるもの。
- 認証、認可処理に成功したもの。
- PATHパラメータ、リクエストbodyのフォーマットがチェックに成功したもの。
- ステータスコードが208の場合(更新なしの場合)、ログは記録されません。

Authorizations:

ConfigurationViewerConfigurationOperatorConfigurationOperatorOperationViewerOperationOperatorOperationOperator

path Parameters

service_code

required

string (ServiceCode) = 11 characters

Example: xpd00000000

サービスコード

query Parameters

next_page_token

string (next_page_token)

Example: next_page_token=eyJpZCI6MTAwfQ

次のページを読み込むためのトークン

Responses

Response samples

200
400
403
500

Content type

application/json

{"request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
"service_code": "xpd00000000",
"result": {"kind": "Log",
"values": [{"time": "2023-07-01T12:23:45.123456+09:00",
"request_id": "AD98019E-BA5A-4F13-902B-AE0609BD0E5D",
"operator": "user1@example.jp",
"operator_id": "573B4CE1-818B-4AC1-B03A-6D51AA396E21",
"operation_id": "SetFilter",
"request_ip": "192.168.0.1",
"request_body": {"kind": "Filter",
"cpb_enabled": true,
"mdb_enabled": false
},
"response_code": 200
},
{"time": "2023-07-01T12:23:45.123456+09:00",
"request_id": "27235F6C-5D09-4529-92F5-7C5871481531",
"operator": "user2@example.jp",
"operator_id": "5B31152D-F6D0-4439-925E-5540201D2A5D",
"operation_id": "SetDoHACL",
"request_ip": "192.168.0.1",
"request_body": {"kind": "DoHACL",
"networks": ["2001:db8::/48",
"203.0.113.0/24"
]
},
"response_code": 200
}
]
},
"next_page_token": "eyJpZCI6MTAwfQ"
}