Help: API 1.13.0+update.3

Moebooru提供的API和Danbooru API (version 1.13.0)大部分相容，能夠讓您更方便的寫指令碼語言。
你需要的是一種GET和POST到URLs的方法。如果您能解析XML或者JSON的響應，這樣更好，但不是很重要，簡單的API意味著你可以用JavaScript, Perl, Python, Ruby甚至像bash或tcsh這樣的shell語言編寫指令碼。

基礎（Basics）

HTTP定義了兩個請求方法：GET和POST。你將使用這兩個方法與Danbooru API進行互動。大部分改變資料庫狀態的API呼叫（例如建立，更新，或者刪除某些內容）需要進行HTTP POST呼叫。只檢索資料的API呼叫通常可以使用HTTP GET呼叫來完成。
在Danbooru API中，URL和函式名類似。您將函式引數作為查詢字串傳遞，這裡是一個非常簡單的栗子：/post.xml?limit=1.

post部分表示我們正在使用的控制器。在這個栗子下是posts.index描述了動作。這裡我們正在檢索帖子列表。最後，xml部分描述了我們想要的響應格式。您可以寫.xml指定為XML響應，.json指定為JSON響應，或者什麼都不寫指定為HTML響應。
.xml效果：

.json效果：

html效果：

響應

所有改變狀態的API呼叫將返回單個元素響應（以XML呼叫為例）他們的格式如下：

<?xml version="1.0" encoding="UTF-8"?>
<response success="false" reason="duplicate"/>
 

對於JSON響應，他們將如下所示：

{success: false, reason: "duplicate"}

您通常可以根據響應物件來決定（呼叫）成功或者失敗，您還可以根據HTTP狀態碼知道發生了什麼。在標準狀態碼之外，Danbooru還使用一些範圍在4xx到5xx的自定義狀態碼。

狀態碼	含義
200 OK	請求成功（Request was successful）
403 Forbidden	拒絕訪問（Access denied）
404 Not Found	沒有找到（Not found）
420 Invalid Record	記錄無法儲存（Record could not be saved）
421 User Throttled	使用者被調節，稍後再試（User is throttled, try again later）
422 Locked	資源被鎖定，無法修改（The resource is locked and cannot be modified）
423 Already Exists	資源已經存在（Resource already exists）
424 Invalid Parameters	給定的引數無效（The given parameters were invalid）
500 Internal Server Error	伺服器上發生一些未知錯誤（Some unknown error occurred on the server）
503 Service Unavailable	伺服器目前無法處理請求，稍後再試（Server cannot currently handle the request, try again later）

JSON響應

在大多數情況下，您可能希望使用XML，如果您在JavaScript中編寫某些內容，那麼JSON響應可能更好。JSON響應能夠更快的被解析並且寫更少的程式碼就可以獲得你的資料結構。栗子：

var data = eval("(" + responseText + ")")
alert(data.response)

登入

有些操作可能要求您登入。對於任何操作，您隨時可以指定兩個引數來標識自己：
login 您的登入名
password_hash 您的SHA1雜湊密碼。簡單的雜湊您的純密碼將不會有效因為Danbooru給它的密碼加Salt了（更難被破解）。實際上被雜湊的字串是”choujin-steiner–your-password–”。
請注意通過未加密的頻道傳送您的密碼所涉及的安全風險。雖然您的密碼將被雜湊，但是理論上仍然有可能根據您的雜湊密碼建立一個假的cookie來竊取您的賬戶。

帖子（Posts）

獲得列表（List）

基本的URL是 /post.xml.
limit 你想要檢索的帖子的數量。每個請求都有最多100個帖子的限制。
page 頁數。
tags 搜尋的tags。在網站上工作的任何標籤組合都可以在這裡工作。這包括了所有的元標記。

建立（Create）

基本的URL是 /post/create.xml.
只有兩個必填的欄位：您需要提供標籤（tags），您需要通過多部分表單或源URL提供檔案。
post[tags] 空格分隔的標籤列表
post[file] 以多部分形式編碼的檔案資料
post[rating] 此post的評級，可以是：安全的（safe），可疑的（questionable），成人向（18+）（explicit）
post[source] 如果這是URL，Danbooru會下載此檔案
post[is_rating_locked] 設定為true以防止其他人改變評級
post[is_note_locked] 設定為true以防止請他人添加註釋
post[parent_id] 父post的ID
md5 如果您希望Danbooru在上傳後驗證該檔案，請提供MD5，如果MD5不匹配，此post被銷燬。

如果呼叫失敗，可能有以下響應原因：
MD5不匹配（MD5 mismatch）這意味著你提供了一個Danbooru 無法匹配的MD5引數，嘗試再次上傳此檔案。
重複（duplicate）這個提交請求（post）已經存在於Danbooru（基於MD5雜湊）中。將設定一個名為location的附加屬性，指向原提交請求的（相對）URL。
其他（other）任何其他的錯誤將打印出其錯誤訊息。
如果提交請求（post）上傳成功，你將會在響應中得到一個名為location屬性，指向你最近上傳的帖子的（相對）URL。

更新（Update）

基本URL是 /post/update.xml. 只需要id引數。如果你不想改變其他引數，則將它們留空。
id 提交請求將要更新的id
post[tags] 空格分隔的標籤列表
post[file] 以多部分形式編碼的檔案資料
post[rating] 此post的評級，可以是：安全的（safe），可疑的（18+）（questionable），明確的（explicit）
post[source] 如果這是URL，Danbooru會下載此檔案
post[is_rating_locked] 設定為true以防止其他人改變評級
post[is_note_locked] 設定為true以防止請他人添加註釋
post[parent_id] 父post的ID

刪除（Destroy）

您必須登入才能使用這個操作。同時，您必須是上傳此帖子的使用者（或者您是主持人moderator）。
id 要刪除的帖子的id號.

恢復標籤（Revert Tags）

此操作恢復一個帖子到之前的標籤集，基本的URL是 /post/revert_tags.xml.
id 要更新的帖子的id號。
history_id 歷史標籤的id號。

投票（Vote）

這個操作讓你給一個帖子投票。你以一個IP地址只能給一個帖子投一票。基本URL是/post/vote.xml.
id 要更新的帖子的id號。
score 設定為1來贊同，設定為-1以否定。所有其他值會被忽略。
如果呼叫不成功，可能因為下面的原因：
already voted 你已經給這個帖子投過票了。
invalid score 你提供了一個無效的分數。

標籤（Tags）

獲得列表（List）

基本URL是 /tag.xml.
limit 檢索的tags的數量。將它設定為0會返回所有tag。
page 頁數
order 排列順序，可以是date, count, 或者 name
id tag的id
after_id 返回所有id比此id更大的tags
name tag的準確名字
name_pattern 搜尋任何名字中包含此引數的tag
一個栗子：

更新（Update）

name 要更新的標籤的名稱
tag[tag_type] tag型別。一般：0，藝術家：1，版權：3，角色：4
tag[is_ambiguous] 這個tag是否不明確，使用1表示不明確，使用0表示明確。

相關（Related）

基本URL是 /tag/related.xml.
tags 詢問的tags名稱
type 將結果限制在此tag型別，可以為general, artist, copyright,或者 character

藝術家（Artists）

獲得列表（List）

基本URL是/artist.xml.
name 藝術家的名字（或名字的片段）
order 排列順序，可以是date或者name
page 獲取的頁數
一個栗子：

建立（Create）

基本URL是 /artist/create.xml.
artist[name] 藝術家的名字
artist[urls] 與此藝術家相關的URLs列表，空格分隔。
artist[alias] 將建立藝術家是此欄位代表藝術家的別名。只需輸入別名。
artist[group] 此藝術家參與的組或圈子。只需輸入該組的名稱。

更新（Update）

基本URL是 /artist/update.xml. 只需要id引數，其他引數是可選的。
id 要更新的藝術家的id
artist[name] 藝術家的名字
artist[urls] 與此藝術家相關的URLs列表，空格分隔。
artist[alias] 將建立藝術家是此欄位代表藝術家的別名。只需輸入別名。
artist[group] 此藝術家參與的組或圈子。只需輸入該組的名稱。

刪除（Destroy）

基本URL是 /artist/destroy.xml. 你必須登入才能刪除藝術家。
id 將要刪除的藝術家的id

評論（Comments）

展示評論（Show）

基本URL是 /comment/show.xml. 這將檢索單個評論。
id 將要檢索的評論的id

建立（Create）

基本URL是/comment/create.xml.
comment[anonymous] 如果你想匿名發表此評論，設定為1.
comment[post_id] 你此評論發表物件的id
comment[body] 評論的正文

刪除（Destroy）

基本URL是 /comment/destroy.xml. 你必須登入才能使用此操作。同時你必須是此評論的發表者或者是主持人。
id 將要刪除的評論的id

Wiki

所有標題必須是準確的（但是樣例（case）和空格無關緊要）

獲得列表（List）

基本的URL是 /wiki.xml. 這將檢索所有wiki頁面構成的列表。
order 你想要的頁面的排列順序。可以是：title，date
limit 要檢索的總頁數
page 檢索特定頁面的頁碼
query 將要搜尋的一個單詞或者片語
一個栗子：

建立（Create）

基本URL是 /wiki/create.xml.
wiki_page[title] 建立的wiki頁面的標題
wiki_page[body] 建立的wiki頁面的正文

更新（Update）

基本URL是 /wiki/update.xml. 可能的報錯原因：“頁面被鎖定”
title 將要更新的wiki頁面的原始標題
wiki_page[title] 此wiki頁面的新標題
wiki_page[body] 此wiki頁面的新正文

展示（Show）

基本URL是 /wiki/show.xml. 可能的報錯原因：“藝術家型別”
title 將檢索的wiki頁面的標題
version 將檢索的wiki頁面的版本

刪除（Destroy）

基本URL是 /wiki/destroy.xml. 你必須以建立人（moderator）身份登入才能使用此操作。
title 將刪除的頁面的標題

鎖定（Lock）

基本URL是 /wiki/lock.xml. 你必須以建立人（moderator）身份登入才能使用此操作。
title 將鎖定的頁面的標題

解鎖（Unlock）

基本URL是 /wiki/unlock.xml. 你必須以建立人（moderator）身份登入才能使用此操作。
title 將解鎖的頁面的標題

還原（Revert）

基本URL是 /wiki/revert.xml. 可能報錯的原因：“頁面被鎖定”
title 將要更新的wiki頁面的標題
version 將此頁面恢復到的版本

歷史（History）

基本URL是 /wiki/history.xml.
title 將要被檢索歷史版本的wiki頁面的title

備註（Notes）

獲得列表（List）

基本URL是 /note.xml.
post_id 將要檢索的備註的post id
一個栗子：

搜尋（Search）

基本URL是 /note/search.xml.
query 將要搜尋的一個單詞或片語

歷史（History）

基本URL是 /note/history.xml. 你可以指定id，post_id或者什麼都不指定。什麼都不指定會給你一個包含所有備註當前版本資訊的列表
limit 檢索歷史版本的數量
page 頁面偏移量
post_id 將要被檢索版本的備註的post id
id 將要被檢索版本的備註的id

恢復（Revert）

基本URL是 /note/revert.xml. 可能的報錯原因：“帖子被鎖定”
id 將要被更新的備註的id
version 此備註將要恢復到的版本

建立/更新（Create/Update）

基本URL是 /note/update.xml. 備註和其他的控制器的不同點在於建立和更新的介面是相同的。如果你提供id引數，那麼Danbooru會假定你正在更新一個現有的備註。否則，它會建立一個新的備註。可能的錯誤原因：“帖子被鎖定”
id 如果你更新一個備註，這是被更新備註的id
note[post_id] 此備註屬於的帖子的id
note[x] 此備註的x座標
note[y] 此備註的y座標
note[width] 此備註的寬度
note[height] 此備註的高度
note[is_active] 此備註是否可見，設定成1為可見，0為不可見
note[body] 此備註的資訊

使用者（Users）

搜尋（Search）

基本URL是 /user.xml. 如果你不指定任何引數，你會得到一個包含所有使用者的列表
id 使用者的id
name 使用者的名稱
一個栗子：

論壇（Forum）

獲得列表（List）

基本URL是 /forum.xml. 如果你不指定任何引數，你會得到一個包含所有父級主題的列表
parent_id 父級主題id，你將會得到該論壇帖子的所有回覆
一個栗子：

同主題圖片集合（Pools）

列表池（List Pools）

基本URL是 /pool.xml. 如果你不指定任何引數，你會得到一個包含所有同主題圖片集合的列表
query 標題
page 頁面
一個栗子：

帖子列表（List Posts）

基本URL是 /pool/show.xml. 如果你不指定任何引數，你會得到一個包含所有同主題圖片集合的列表
id 此圖片集合的id
page 圖片集合的頁數

更新（Update）

基本URL是 /pool/update.xml.
id 此圖片集合的id
pool[name] 此圖片集合的名稱
pool[is_public] 值為1或0，1代表這個圖片集合是公開的，0表示非公開
pool[description] 此圖片集合的描述

建立（Create）

基本URL是 /pool/create.xml.
pool[name] 此圖片集合的名稱
pool[is_public] 值為1或0，1代表這個圖片集合是公開的，0表示非公開
pool[description] 此圖片集合的描述

刪除（Destroy）

基本URL是 /pool/destroy.xml.
id 將要刪除的圖片集合的id

增加帖子（Add Post）

基本URL是 /pool/add_post.xml. 可能的報錯原因：“帖子已經存在”，“訪問被拒絕”
pool_id 將要新增此帖子的圖片集合的id
post_id 將要新增的帖子的id

刪除帖子（Remove Post）

基本URL是 /pool/remove_post.xml. 可能的錯誤原因：“訪問被拒絕”
pool_id 將要刪除此帖的圖片集合的id
post_id 將要被刪除的帖子的id

喜愛此圖片的使用者（Favorites）

喜愛此圖片的使用者列表（List Users）

基本URL是 /favorite/list_users.json 此操作沒有XML型別的API
id 此圖片帖子的id
一個栗子：

更新日誌（Change Log）

1.13.0+update.3

把 “/index” 從API的URLs移除

1.13.0+update.2

重新新增 “favorite/list_users” 的API

1.13.0+update.1

給同主題圖片集合（Pools）新增文件

1.13.0

修改藝術家有關的介面以使用新的URL系統
JSON請求現在會以.json字尾結尾
重新命名了一些錯誤原因資訊
把 “comment/index” 從API中移除
把url和md5引數從藝術家搜尋中移除（可以將URL或者MD5雜湊當做名稱引數傳遞）

1.8.1

去掉 post[is_flagged] 屬性