Gehirn DNS API 仕様

Posted on Fri, Dec 18, 2015 in Work tagged with Gehirn

追記

ゲヒルン株式会社として公式に Gehirn DNS を含む Gehirn Web Services API Documentation を公開したので、今後はそちらを参照して下さい。今後、この非公式ドキュメントはメンテナンスしません。

はじめに

このドキュメントは、ゲヒルン株式会社が Public Preview で提供している Gehirn DNS の API 仕様を説明するものです。ただし、これはゲヒルン株式会社として提供する公式なドキュメントではなく、あくまでも個人として、公式のドキュメントが公開されるまでの期間、暫定的に公開するものです。

また、ここで説明する仕様は、2015年12月21日17時に予定しているメンテナンスが終了した後に有効となります。

API 仕様

Root endpoint: https://api.gis.gehirn.jp/dns/v1
Content-Type: application/json
Authentication: API キーを用いた Basic 認証

認証

すべてのリクエストで認証が必要となります。認証様式は、 API キーのトークンを usreid 、シークレットセールを password とする Basic 認証です。

API キーはコントロールパネルから発行することができます。また、リクエストに用いる API キーには適切な権限が設定されている必要があります。

Gehirn DNS の操作で必要になる権限は [DNS] -> [全般管理] -> [ゾーン] と [DNS] -> [ドメイン] -> [操作対象のゾーン] で、それぞれ読み取り以上が必要です。読み取りは HTTP Verb の GET に、フルアクセスは HTTP Verb の GET に加え、 POST 、 PUT 、そして DELETE に対応します。

リクエスト

API を用いて行える操作は以下に示すとおりです。行いたい操作に合わせて、 Root endpoint と当該 Path からなるエンドポイントに対して、当該 HTTP Verb を用いたリクエストを行って下さい。

リクエストボディが必要な場合は、当該 JSON Schema に適合する形式の JSON を送信して下さい。なお、この場合 Content-Type: application/json リクエストヘッダーが必要となります。

ゾーン

JSON Schema

{
  "type": "object",
  "properties": {
    "id": {
      "minLength": 36,
      "type": "string",
      "maxLength": 36
    },
    "name": {
      "minLength": 4,
      "type": "string",
      "maxLength": 256
    },
    "current_version_id": {
      "minLength": 36,
      "type": "string",
      "maxLength": 36
    },
    "current_version": {
      "type": "object",
      "properties": {
        "id": {
          "minLength": 36,
          "type": "string",
          "maxLength": 36
        },
        "name": {
          "minLength": 1,
          "type": "string",
          "maxLength": 255
        }
      }
    }
  }
}

フィールド	意味	リクエスト時要否
id	ゾーンを特定する一意な ID	不要
name	ドメイン名	必要
current_version_id	現在アクティブなバージョンの ID	不要
current_version	現在アクティブなバージョン	不要

ゾーンの作成

Path: /zones
HTTP Verb: POST
Request Body: 必要

リクエスト例

POST /dns/v1/zones HTTP/1.1
Host: api.gis.gehirn.jp
Content-Type: application/json
Authorization: Basic dG9rZW46c2VjcmV0

{
    "name": "yaml.jp"
}

レスポンス例

HTTP/1.1 200 OK
Server: nginx
Date: Fri, 18 Dec 2015 10:41:01 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 388

{
  "id": "92e52aab-81ac-4c87-b659-b7b36e05cb7f",
  "name": "yaml.jp",
  "current_version_id": "234b6f0e-8b64-4cd9-8647-16cd26133266",
  "current_version": {
    "id": "234b6f0e-8b64-4cd9-8647-16cd26133266",
    "editable": true,
    "name": "\u6700\u521d\u306e\u30d0\u30fc\u30b8\u30e7\u30f3",
    "created_at": "2015-03-05T10:49:04Z",
    "last_modified_at": "2015-03-05T10:49:04Z"
  }
}

ゾーンのリストの取得

Path: /zones
HTTP Verb: GET
Request Body: 不要

ゾーンの取得

Path: /zones/:zone_id
HTTP Verb: GET
Request Body: 不要

ゾーンの削除

Path: /zones/:zone_id
HTTP Verb: DELETE
Request Body: 不要

バージョン

JSON Schema

{
  "type": "object",
  "properties": {
    "id": {
      "minLength": 36,
      "type": "string",
      "maxLength": 36
    },
    "name": {
      "minLength": 1,
      "type": "string",
      "maxLength": 255
    }
  }
}

フィールド	意味	リクエスト時要否
id	バージョンを特定する一意な ID	不要
name	任意のバージョン名	必要
editable	編集可否	不要
created_at	バージョン作成時刻	不要
last_modified_at	バージョン最終更新時刻	不要

バージョンの作成

Path: /zones/:zone_id/versions
HTTP Verb: POST
Request Body: 必要

リクエスト例

POST /dns/v1/zones/234b6f0e-8b64-4cd9-8647-16cd26133266/versions HTTP/1.1
Host: api.gis.gehirn.jp
Content-Type: application/json
Authorization: Basic dG9rZW46c2VjcmV0

{
    "name": "新しいバージョン"
}

レスポンス例

HTTP/1.1 200 OK
Server: nginx
Date: Fri, 18 Dec 2015 10:41:01 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 218

{
  "id": "f66504b0-bb65-4766-9d7c-18c4e8406071",
  "editable": true,
  "name": "\u65b0\u3057\u3044\u30d0\u30fc\u30b8\u30e7\u30f3",
  "created_at": "2015-12-18T10:49:13Z",
  "last_modified_at": "2015-12-18T10:49:13Z"
}

バージョンリストの取得

Path: /zones/:zone_id/versions
HTTP Verb: GET
Request Body: 不要

バージョンの取得

Path: /zones/:zone_id/versions/:version_id
HTTP Verb: GET
Request Body: 不要

バージョンの編集

Path: /zones/:zone_id/versions/:version_id
HTTP Verb: PUT
Request Body: 必要

バージョンの削除

Path: /zones/:zone_id/versions/:version_id
HTTP Verb: DELETE
Request Body: 不要

レコードセット

JSON Schema

{
  "type": "object",
  "properties": {
    "id": {
      "minLength": 36,
      "type": "string",
      "maxLength": 36
    },
    "name": {
      "minLength": 1,
      "type": "string",
      "maxLength": 256
    },
    "type": {
      "minLength": 1,
      "type": "string",
      "maxLength": 5
    },
    "enable_alias": {
      "type": "boolean"
    },
    "alias_to": {
      "minLength": 1,
      "type": "string",
      "maxLength": 256
    },
    "ttl": {
      "minimum": 30,
      "type": "integer",
      "maximum": 2147483647
    },
    "records": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "prio": {
            "minimum": 0,
            "type": "integer",
            "maximum": 32767
          },

          "address": {
            "minLength": 3,
            "type": "string",
            "maxLength": 39
          },

          "cname": {
            "minLength": 1,
            "type": "string",
            "maxLength": 256
          },

          "exchange": {
            "minLength": 1,
            "type": "string",
            "maxLength": 256
          },

          "nsdname": {
            "minLength": 1,
            "type": "string",
            "maxLength": 256
          },

          "target": {
            "minLength": 1,
            "type": "string",
            "maxLength": 256
          },
          "port": {
            "minimum": 0,
            "type": "integer",
            "maximum": 65535
          },
          "weight": {
            "minimum": 0,
            "type": "integer",
            "maximum": 65535
          },

          "data": {
            "minLength": 1,
            "type": "string",
            "maxLength": 64000
          }
        }
      }
    }
  }
}

フィールド	意味	リクエスト時要否
id	レコードセットを特定する一意な ID	不要
name	ホストネーム	必要
type	レコードタイプ (A, AAAA, CNAME, MX, NS, SRV, TXT)	必要
enable_alias	エイリアス機能利用	必要
alias_to	エイリアス先 (エイリアス機能利用時)	enable_alias が true の時のみ
ttl	TTL	enable_alias が false の時のみ
records	レコードのリスト	enable_alias が false の時のみ
records.prio	Priority	type が MX または SRV の時のみ
records.address	IPv4 または IPv6 アドレス	type が A または AAAA の時のみ
records.cname	CNAME	type が CNAME の時のみ
records.exchange	メールサーバーのドメインネーム	type が MX の時のみ
records.nsdname	ネームサーバーのドメインネーム	type が NS の時のみ
records.target	ターゲットのドメインネーム	type が SRV の時のみ
records.port	ターゲットのポート番号	type が SRV の時のみ
records.weight	ターゲットの重み	type が SRV の時のみ
records.data	TXT データ	type が TXT の時のみ

レコードセットの作成

Path: /zones/:zone_id/versions/:version_id/records
HTTP Verb: POST
Request Body: 必要

リクエスト例

POST /dns/v1/zones/234b6f0e-8b64-4cd9-8647-16cd26133266/versions/f66504b0-bb65-4766-9d7c-18c4e8406071/records HTTP/1.1
Host: api.gis.gehirn.jp
Content-Type: application/json
Authorization: Basic dG9rZW46c2VjcmV0

{
  "name": "yaml.jp.",
  "ttl": 300,
  "type": "A",
  "enable_alias": false,
  "records": [
    {
      "address":"192.0.2.10"
    },
    {
      "address":"192.0.2.11"
    }
  ]
}

レスポンス例

HTTP/1.1 200 OK
Server: nginx
Date: Fri, 18 Dec 2015 10:41:01 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 218

{
  "id": "e590d62a-3676-4b08-832a-a1fdd6dfefdf",
  "name": "yaml.jp.",
  "type": "A",
  "enable_alias": false,
  "ttl": 300,
  "records": [
    {
      "address": "192.0.2.10"
    },
    {
      "address": "192.0.2.11"
    }
  ]
}

レコードセットリストの取得

Path: /zones/:zone_id/versions/:version_id/records
HTTP Verb: GET
Request Body: 不要

レコードセットの取得

Path: /zones/:zone_id/versions/:version_id/records/:record_id
HTTP Verb: GET
Request Body: 不要

レコードセットの編集

Path: /zones/:zone_id/versions/:version_id/records/:record_id
HTTP Verb: PUT
Request Body: 必要

レコードセットの削除

Path: /zones/:zone_id/versions/:version_id/records/:record_id
HTTP Verb: DELETE
Request Body: 不要

yosida95

著者について / About yosida95

ここで述べる内容は私個人の見解に基づくものであり、私の雇用者や私が所属する団体とは一切の関係がありません。

Follow @yosida95

Gehirn DNS API 仕様

追記

はじめに

API 仕様

認証

リクエスト

ゾーン

JSON Schema

ゾーンの作成

ゾーンのリストの取得

ゾーンの取得

ゾーンの削除

バージョン

JSON Schema

バージョンの作成

バージョンリストの取得

バージョンの取得

バージョンの編集

バージョンの削除

レコードセット

JSON Schema

レコードセットの作成

レコードセットリストの取得

レコードセットの取得

レコードセットの編集

レコードセットの削除

yosida95

Recent Articles

Categories

Archives