Wikidot API

原文: http://www.wikidot.com/doc:api

コマンド名称の基本理念は以下のものになります。

• 名前空間は指定するオブジェクトの種類を示します
• selectメソッドは対象の名称(String)の配列を返します
• getメソッドは条件に適合したデータの全プロパティを有するオブジェクトを要素として持つリストを返します
• get_oneメソッドは条件に適合した単一のデータの全プロパティを有するオブジェクトを唯一の要素として持つリストを返します

本ページはメソッドの追加に伴い加筆修正が行われます。本ページでは各メソッドの説明を行います。

categories.select

指定したサイトに存在する全てのカテゴリを取得します。

• 引数に使用するキー
  • site: カテゴリ取得先のサイト名, 例. "my-site"
• 返り値: カテゴリ名称のリスト

>>> s.categories.select({"site": "my-site"})
["_default", "admin", "forum", "system", "blog"]

files.select

指定したサイトの指定のページに添付されたファイル名を取得します。

• 引数に使用するキー
  • site: 問合せを行うサイト
  • page: 問い合わせを行うページ(full name指定)
• 返り値: 添付ファイル名リスト

files.get_meta

指定した複数のファイルのメタデータを取得します。

• 引数に使用するキー
  • site: 問合せを行うサイト
  • page: 問い合わせを行うページ(full name指定)
  • files: メタデータの取得を行うファイルのリスト(最大10個まで指定可能)
• 返り値: ファイルデータのdictionaryオブジェクト。ファイル名をキーとします。各要素が持つプロパティは以下になります。
  • size — ファイルの大きさ（単位: バイト)
  • comment
  • mime_type
  • mime_description
  • uploaded_by
  • uploaded_at
  • download_url — ファイルをダウンロードする為のURLです。プライベートサイトの場合5分間有効の認証トークンが"?ukey=…"の形式で付与されます。

files.get_one

このメソッドは小さいサイズのファイルにしか動きません（最大6MB)。

指定したページに添付されたファイルを取得できます（もしくはget_metaメソッドで取得したdownload_urlから取得する事もできます）。

• 引数に使用するキー
  • site: ファイル取得先サイト
  • page: ファイル取得先ページ
  • file: 取得するファイルの名称
• 返り値: files.get_metaメソッドで取得できるデータのプロパティに下記のプロパティを加えたdictionaryオブジェクト。
  • content — base64にエンコードされたファイルの内容データ

files.save_one

50MB以下のファイルに対して使用できます。また下記に示すような他のファイルサイズ制限も適用されます。

• サイトの残ストレージ — 現在の未使用ストレージを超えるサイズのファイルをアップロードする事はできません。
• free及びproのプランに応じた最大ファイルサイズ

任意のファイルを指定のページに添付します。

• 引数に使用するキー
  • site: ファイル添付先サイト
  • page: ファイル添付先ページ
  • file: 添付するファイル名
  • comment (省略可): ファイルの説明文
  • save_mode(省略可): 下記のモードから選べます。
    • create — 新規ファイルの添付のみ許可します (fileで指定した名前のファイルが既に存在する場合、例外を飛ばします)
    • update — 既存ファイルの更新のみ許可します (fileで指定した名前のファイルが存在しない場合、例外を飛ばします)
    • create_or_update(規定値) — 新規ファイル作成及び既存ファイル更新のどちらも許可します
  • content: base64に変換したファイルの内容データ
  • notify_watchers(省略可):
    • true: ウォッチャーに対してWebページで編集された時と同様にページの編集を通知します。
    • false(規定値): ウォッチャーに対して通知を行いません。
  • revision_comment (省略可): 編集履歴に表示するリビジョンのコメント
• 返り値: 作成/更新を行ったファイルについての情報(files.get_metaで取得できるオブジェクトと同じ構成のdictionaryオブジェクト)。

tags.select

指定したサイト全体、指定したカテゴリ、指定したページのいずれかを対象として付与された全てのタグを取得します。

• 引数に指定するキー
  • site: タグ取得先のページを持つサイト, 例. "my-site"
  • categories (省略可): ページからタグを取得するカテゴリのリスト
  • pages (省略可): タグ取得先のページのリスト（full name指定) — 最大10ページ
• 返り値: タグのリスト

pages.select

特定の条件に一致するページを取得します

• 引数に指定するキー（特に指定が無い限り、指定可能な値はListPagesモジュールに記載されています）
  • site: 取得先のページを持つサイト, 例. "my-site"
  • pagetype (省略可): 規定値 "*"
  • categories (省略可): ページを取得するカテゴリのリスト, 規定値: 全カテゴリ
  • tags_any (省略可): タグのリスト。このリストに登録したタグの内を最低限1つ同一のタグを有しているページのみ取得する
  • tags_all (省略可): タグのリスト。このリストに登録したタグ全てと同一のタグを有しているページのみ取得する
  • tags_none (省略可): タグのリスト。このリストに登録したタグのいずれかと同一のタグを有して居るページは取得しない
  • parent (省略可): 取得するページの親ページ、もしくは親ページを持たない場合は"-"を指定する
  • created_by (省略可): 単一のアカウント名
  • rating (省略可)
  • order (省略可)
• 返り値: ページのfullnameのリスト

>>> s.pages.select({"site": "my-site", "categories": ["blog", "news"], "tags_none": ["_draft"], "order": "created_at desc"})
["blog:last-post", "blog:second-post", "blog:first-post", "blog:_template"]

pages.get_meta

大量のページを取得し、メタデータ（の一部）を返します

• 引数に指定するキー
  • site: メタデータを取得する複数のページを所有するサイト, 例."my-site"
  • pages: メタデータを取得するページのfullnameのリスト (最大10ページ)
• 返り値:
  • fullname
  • created_at
  • created_by
  • updated_at
  • updated_by
  • title
  • parent_fullname
  • tags — 所有する全タグ (アンダースコアで始まる隠しタグも含む)
  • rating
  • revisions
  • [検討中] comments — コメント数
  • [検討中] files — ページに付与されたファイル数
  • [検討中] children — そのページ配下の子ページ数

>>> s.pages.meta({"site": "my-site", "pages": ["blog:last-post", "blog:second-post"]})``
{
"blog:last-post": {"fullname": "blog:last-post", "created_at": "2010-08-04T23:20:50Z", "created_by": "Gabrys", "updated_at": "2010-08-04T23:23:31Z", "updated_by": "Gabrys", "title": "Last Post", "parent_fullname": None, "tags": ["blog", "last"], "rating": 8, "revisions": 2},
"blog:second-post": {"fullname": "blog:second-post", "created_at": "2010-08-03T22:52:10Z", "created_by": "Gabrys", "updated_at": "2010-08-03T22:52:10Z", "updated_by": "Gabrys", "title": "Second Post", "parent_fullname": None, "tags": ["blog", "second"], "rating": 1, "revisions": 1}
}

pages.get_one

単一のページの全プロパティを取得します。

• 引数に指定するキー
  • site: ページ取得先のサイト名, 例. "my-site"
  • page: 取得を行うページのfullname, 例. "start" または "blog:first-post"
• 返り値: dictionary型のページプロパティ (ListPagesモジュールのドキュメントを参照してください)
  • pages.get_metaで取得できるプロパティに以下を加えたもの:
  • parent_title
  • children
  • content — ページの内容。もしそのページにフォームが割り当てらている場合、取得形式はYAMLです
  • html — HTML出力されたページ (ブラウザが取得するページの内容からナビゲーションバー等を除いた内容です)
  • comments — コメント数
  • commented_at
  • commented_by

>>> s.pages.get_one({"site": "my-site", "page": "blog:last-post"})
{"created_at": "2010-08-04T23:20:50Z", "created_by": "Gabrys", "updated_at": "2010-08-04T23:23:31Z", "updated_by": "Gabrys", "title": "Last Post", "parent_fullname": None, "tags": ["blog", "last"], "rating": 8, "revisions": 2, "parent_title": None, "children": 0, "content": "Test blog post", "html": "<p>Test blog post</p>", "comments": 0, "commented_at": None, "commented_by": None}

pages.save_one

ページを保存します。引数として数字配列のサイトキーとページキーが必要になります。特定のキーを設定しプロパティを更新します。キーを省略した場合は現在の値が保存されます。

• 引数に指定するキー
  • site: ページを保存するサイト
  • page: 保存を行うページのfullname
  • title (省略可): ページのタイトル
  • content (省略可): ページの内容 — wiki構文を使う
  • tags (省略可): ページに保存するタグ配列
  • parent_fullname (省略可): 親ページのfullname, 親ページ解除時は"-"を入力
  • save_mode (省略可): 下記モードが選択できます
    • create — ページの新規作成のみを許可します (同名のページが存在する場合例外を発行します)
    • update — ページの更新のみを許可します (指定のページが存在しない場合例外を発行します)
    • create_or_update (規定値) — 新規作成と更新両方許可します
  • rename_as (省略可): pagenameを変更します (ページソース等の他の変更可能なプロパティの更新に加えても使用できます)
  • revision_comment (省略可): リビジョンコメント (履歴に表示されます)
  • notify_watchers (省略可):
    • true: ウォッチャーに対してWebページで編集された時と同様にページの編集を通知します
    • false (規定値): ウォッチャーに対して通知を行いません
• 返り値: saved page (pages.get_oneと同様)

現在、コメント専用のAPIの開発を試みていますが、これはコメントとフォラームの両方に拡張されます。その為、っこのメソッドの名前空間はcommentsではなくpostsになります。

posts名前空間のAPIはまだ安定していないことに注意してください。これは、将来予告なしに変更され、互換性が失われる可能性があることを意味します。

posts.select

指定のサイト、ページ、スレッドもしくは指定コメントへの返信を指定して、コメントもしくはフォーラムの投稿を取得します。

• 引数に指定するキー
  • site: コメントを取得先のページを保存しているサイト名, 例. "my-site"
  • page (省略可): コメント取得先のページ名
  • thread (省略可): 投稿取得先のスレッド — 未実装
  • reply_to (省略可): ここで指定したポストもしくは投稿に対する直接の返信のみを取得します ("-"は他のコメントもしくは投稿に対する返信ではないものを意味します)
  • created_by (省略可): 指定したユーザによる投稿を取得します
• returns: 日付によってソートされたコメントもしくは投稿のIDのリスト

posts.get

• 引数に指定するキー
  • site: コメントを取得するサイト名, 例. "my-site"
  • posts: 取得を行うコメントもしくは投稿のIDリスト (最大10個)
• 投稿もしくはコメントのdictionary型のデータを返します。各投稿及びコメントに対して投稿/コメントのIDをキーとし、下記のプロパティーを有するdictionary型のデータを生成して返します:
  • id — 投稿もしくはコメントのID
  • fullname — そのコメントが投稿されたページのfullname
  • reply_to — その投稿もしくはコメントの返信先の投稿もしくはコメントのID
  • title — その投稿もしくはコメントのタイトル
  • content — wiki構文による投稿もしくはコメントの内容
  • html — HTMLによる投稿もしくはコメントの内容
  • created_by — その投稿もしくはコメントをおこなったユーザ名
  • created_at — その投稿もしくはコメントが行われた日付
  • replies — その投稿もしくはコメントに対する返信数 — 未実装

users.get_me

• 引数に指定するキー
  • 引数は不要です。空のdictionary型のデータもしくは配列を渡します
• そのAPIキーに紐づけられた単独のユーザに関する下記プロパティを有するdictionary型のデータを返します:
  • name: URLで指定する際のユーザ名, 例えば"John Smith"からの "john-smith"
  • title: ユーザのfullname, 例えば "John Smith"
  • id: 数字のID, 例えば "12345"

Deleted methods

下記のメソッドは削除され、現在は使用できません。

• site.pages
• site.categories
• page.get
• page.files
• page.save
• user.sites