本文書は、IIJ xSPプラットフォームサービス/キャッシュDNSのユーザ用のAPI(以下XDNS-API)を定義しています。 本文書は、OpenAPIに準拠しています。
このWEBページはopenapi.jsonから自動生成しています。このWEBページとopenapi.jsonの内容が異なる場合は、openapi.jsonの内容を正とします。 openapi.jsonは、上部のDownloadボタンからダウンロードできます。
XDNS-APIを呼び出すためのプログラム、及びそのプログラムを稼働させるためのサーバは、お客様にてご用意ください。
お客様にご用意いただくプログラムの開発、利用、動作についてのお問い合わせは承ることができません。
以下の事項についてのお問い合わせは、弊社サポートセンターにて承ります。
XDNS-APIは、URLとHTTPリクエストヘッダ、HTTPリクエストボディでパラメータを指定して利用します。
また、IIJ IDサービスのアクセストークンと管理対象の権限設定が必要です。
| 項目 | 規格 |
|---|---|
| プロトコル | HTTP/1.1、HTTP/2（https） |
| HTTPメソッド | GET、POST、PUT |
| フォーマット | JSON |
| 文字コード | UTF-8 |
| タイムアウト | 300秒 |
APIリクエストの際にIIJ IDサービスによって発行されたアクセストークンをAuthorizationヘッダに指定する必要があります。
各APIにより必要となるアクセス権の範囲（許可するスコープ）が異なるのでご注意ください。
アクセストークン作成時に指定できる「許可するスコープ」は以下のとおりです。
| 許可するスコープ | 実行できるAPI |
|---|---|
| xdns_read | 参照系API |
| xdns_write | 参照系API, 更新系API |
発行済のアクセストークンは、IIJ IDサービスの「アクセストークンの管理」より確認できます。
XDNS-APIを利用する場合は「利用するリソースサーバ」の設定で「IIJ xSPプラットフォームサービス/キャッシュDNS」を選択してください。
アクセストークン管理方法のマニュアルはこちらを参照してください。
XDNSでは、管理対象となる契約単位での参照、編集権限を細かく設定できます。
アクセストークンの許可するスコープが適切であっても、管理対象の権限が付与されていない場合は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形式のパラメータ |
| service_code required | string (ServiceCode) = 11 characters Example: xpd00000000 サービスコード |
{- "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."
]
}
}| service_code required | string (ServiceCode) = 11 characters Example: xpd00000000 サービスコード |
required | object |
| kind required | string Value: "ContractMetadata" |
{- "labels": {
- "description": "絵文字も利用可能🍺",
- "name": "for west Japan",
- "example.jp/hoge": "ドメイン部＋ラベル部のkey",
- "example_code": "hogehoge",
- "example.jp/Code_Red": "false"
}, - "kind": "ContractMetadata"
}{- "request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
- "service_code": "xpd00000000"
}| service_code required | string (ServiceCode) = 11 characters Example: xpd00000000 サービスコード |
{- "request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
- "service_code": "xpd00000000",
- "result": {
- "kind": "APIACL",
- "networks": [
- "2001:db8::/48",
- "203.0.113.0/24"
]
}
}| service_code required | string (ServiceCode) = 11 characters Example: xpd00000000 サービスコード |
| kind required | string Value: "APIACL" |
| networks required | Array of strings (Networks) <= 10000 items unique
|
{- "kind": "APIACL",
- "networks": [
- "2001:db8::/48",
- "203.0.113.0/24"
]
}{- "request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
- "service_code": "xpd00000000"
}| service_code required | string (ServiceCode) = 11 characters Example: xpd00000000 サービスコード |
{- "request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
- "service_code": "xpd00000000",
- "result": {
- "kind": "DNSACL",
- "networks": [
- "2001:db8::/48",
- "203.0.113.0/24"
]
}
}| service_code required | string (ServiceCode) = 11 characters Example: xpd00000000 サービスコード |
| kind required | string Value: "DNSACL" |
| networks required | Array of strings (Networks) <= 10000 items unique
|
{- "kind": "DNSACL",
- "networks": [
- "2001:db8::/48",
- "203.0.113.0/24"
]
}{- "request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
- "service_code": "xpd00000000"
}| service_code required | string (ServiceCode) = 11 characters Example: xpd00000000 サービスコード |
{- "request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
- "service_code": "xpd00000000",
- "result": {
- "kind": "DoHACL",
- "networks": [
- "2001:db8::/48",
- "203.0.113.0/24"
]
}
}| service_code required | string (ServiceCode) = 11 characters Example: xpd00000000 サービスコード |
| kind required | string Value: "DoHACL" |
| networks required | Array of strings (Networks) <= 10000 items unique
|
{- "kind": "DoHACL",
- "networks": [
- "2001:db8::/48",
- "203.0.113.0/24"
]
}{- "request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
- "service_code": "xpd00000000"
}| service_code required | string (ServiceCode) = 11 characters Example: xpd00000000 サービスコード |
{- "request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
- "service_code": "xpd00000000",
- "result": {
- "kind": "DNSFilter",
- "cpb_enabled": true,
- "mdb_enabled": true
}
}| service_code required | string (ServiceCode) = 11 characters Example: xpd00000000 サービスコード |
| kind required | string Value: "DNSFilter" |
| cpb_enabled required | boolean 児童ポルノブロッキング機能の有効状態 |
| mdb_enabled required | boolean 悪性ドメイン名フィルタリング機能の有効状態 |
{- "kind": "DNSFilter",
- "cpb_enabled": true,
- "mdb_enabled": true
}{- "request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
- "service_code": "xpd00000000"
}| service_code required | string (ServiceCode) = 11 characters Example: xpd00000000 サービスコード |
| kind required | string Value: "ClearCacheRequest" |
| domains required | Array of strings [ 1 .. 100 ] items unique [ items <= 254 characters ] キャッシュクリアを要求する、ドメイン名のリスト。FQDN形式（末尾.あり）。IDNの場合はpunycodeにしたものを指定 |
{- "kind": "ClearCacheRequest",
- "domains": [
- "hogehoge.example.jp.",
- "example.com.",
- "xn--eckwd4c7cu47r2wf.jp.",
- "202.in-addr.arpa.",
- "3.5.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.4.2.0.1.0.0.2.ip6.arpa."
]
}{- "request_id": "7a0137c7-22d0-4e7a-a240-fa595aa13e29",
- "service_code": "xpd00000000"
}| service_code required | string (ServiceCode) = 11 characters Example: xpd00000000 サービスコード |
{- "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
}
]
}
}| service_code required | string (ServiceCode) = 11 characters Example: xpd00000000 サービスコード |
| next_page_token | string (next_page_token) Example: next_page_token=eyJpZCI6MTAwfQ 次のページを読み込むためのトークン |
{- "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": "SetClearCacheTarget",
- "request_ip": "192.168.0.1",
- "request_body": {
- "kind": "CacheClear",
- "domains": [
- "example.jp.",
- "example.com."
]
}, - "response_code": 200
}
]
}, - "next_page_token": "eyJpZCI6MTAwfQ"
}