Wretch API 文件 - Version 1.0

API 中需驗證的方法

所有與使用者私人資料有關的都需要使用 OAuth 做驗證，請參考此篇文章：Yahoo! OAuth Quick Start Guide

API 存取方式：

http://wretch.yahooapis.com/v1/[API Method]?[Parameters]

API 的輸出格式：

Wretch API 提供兩種輸出格式：XML 與 JSON，可使用 format 參數來指定回傳的格式 (例如：format=json)，或在發出 Request 時，指定 header 為 application/xml 或 application/json。

若status_code=200, 表示query format正確, 且有 result
若status_code=204, 表示query format正確, 但沒有 result (ex: 相簿裡沒有相片)
若status_code=404, 表示query format有誤, 包含: error typing, 格式錯誤, 或是此resource不存在 (ex: 沒開啟服務) 等
若status_code=406, 表示沒有指定valid accept format (包含 application/xml 及 application/json), 請用 format 參數指定或是在request header中的 accept 指定為 valid value

API 方法列表：

profileService/[guid]：取得 user 個人資料
profileService/[guid]/idTransformation：轉換 user 的 GUID 為 WID
profileService/[guid]/cover/[cover_size]：取得 user 大頭貼
albumService/[guid]：取得 user 相簿服務狀態
albumService/[guid]/albums：取得 user 相簿列表
albumService/[guid]/albums：開一本新相簿 (POST)
albumService/[guid]/categories：取得 user 相簿個人分類列表
albumService/[guid]/album/[album_id]：取得 user 某一本相簿之相片列表
albumService/[guid]/album/[album_id]：在 user 的某一本相簿上傳一張照片 (POST)
albumService/[guid]/album/[album_id]/photo/[photo_id]：取得 user 的某一張相片的相關資訊
blogService/[guid]：取得 user 網誌服務狀態
blogService/[guid]/categories：取得 user 網誌個人分類列表
blogService/[guid]/category/[category_id]：取得 user 網誌屬於某一個人分類之文章列表
blogService/[guid]/articles：取得 user 文章列表
blogService/[guid]/articles：在 user 的 blog 發表文章 (POST)
blogService/[guid]/article/[article_id]：取得 user 的某篇文章資訊及文章的前三行預覽
videoService/[guid]：取得 user 影音服務狀態
videoService/[guid]/videoes：取得 user 影音列表
videoService/[guid]/videoes：上傳一則影音 (POST)
videoService/[guid]/video/[video_id]：取得 user 某則影音及該則影音之相關資訊
videoService/[guid]/categories：取得 user 影音個人分類列表
videoService/[guid]/category/[category_id]：取得 user 某個影音分類下的影音列表
friendService/[guid]：取得 user 好友服務狀態
friendService/[guid]/friends：取得 user 的好友列表
friendService/[guid]/friendGroups：取得 user 的好友群組列表
friendService/[guid]/friendGroup/[group_id]：取得 user 的某一好友群組列表
friendService/[guid]/mutualFriends：取得與 user 互加好友列表
friendService/[guid]/reverseFriends：取得加此 user 為好友之列表
diguService/[guid]：取得 user digu 的服務狀態
diguService/[guid]/messages：發表(回覆) digu 訊息 (POST)
diguService/[guid]/message/[msg_id]：取得 user 所發表的某則 digu 訊息
diguService/[guid]/message/[msg_id]：刪除 user 所發表的 digu 訊息 (DELETE)
diguService/[guid]/myDigus：取得 user 的 "我的嘀咕"
diguService/[guid]/allDigus：取得 user 的 "一起嘀咕"
diguService/[guid]/diguReplies：取得 user 的 "對我嘀咕"
diguService/[guid]/followers：取得 user 的訂閱列表
diguService/[guid]/followings：取得訂閱 user 的列表
diguService/[guid]/subscriptions：訂閱 user 的嘀咕 (POST)
diguService/[guid]/subscription：取消訂閱 user 的嘀咕 (DELETE)
siteAlbumCategories：取得相簿全站分類列表
siteVideoCategories：取得影音全站分類列表
siteDiguAnnounces：取得 20 則全站最新嘀咕

profileService/[guid]
取得 user 個人資料

範例 Request : http://wretch.yahooapis.com/v1/profileService/ZKWHF6P5LXDZSICROTM76OS4CI

參數名稱	是否必填	預設值	說明
guid	是

profileService/[guid]/idTransformation
轉換 user 的 GUID 為 WID

範例 Request : http://wretch.yahooapis.com/v1/profileService/ZKWHF6P5LXDZSICROTM76OS4CI/idTransformation

參數名稱	是否必填	預設值	說明
guid	是

profileService/[guid]/cover/[cover_size]
取得 user 大頭貼

範例 Request : http://wretch.yahooapis.com/v1/profileService/ZKWHF6P5LXDZSICROTM76OS4CI/cover/90

參數名稱	是否必填	預設值	說明
guid	是
cover_size	是		{60, 90, 200, origin}

albumService/[guid]
取得 user 相簿服務狀態

範例 Request : http://wretch.yahooapis.com/v1/albumService/ZKWHF6P5LXDZSICROTM76OS4CI

參數名稱	是否必填	預設值	說明
guid	是

albumService/[guid]/albums
取得 user 相簿列表

範例 Request : http://wretch.yahooapis.com/v1/albumService/ZKWHF6P5LXDZSICROTM76OS4CI/albums?start=1&count=10

參數名稱	是否必填	預設值	說明
guid	是
start	否	1	此值為頁碼
count	否	1	此值為每頁 show 多少本相簿

albumService/[guid]/albums
開一本新相簿 (POST)

範例 Request : http://wretch.yahooapis.com/v1/albumService/ZKWHF6P5LXDZSICROTM76OS4CI/albums

參數名稱	是否必填	預設值	說明
guid	是
isCloak	否	0	保護方式: 完全開放(0), 完全隱藏(1), 密碼保護(2), 好友保護(3)
class_id	是		全站分類
category_id	否		個人分類
location	否		相簿地點

以下參數必須以 "XML的格式" 帶在 "Content" 中

參數名稱	是否必填	說明
title	是	相簿標題
desc	否	相簿描述
passwd	否	密碼保護之密碼
passwd_note	否	密碼保護之提示

Example:
<?xml version="1.0" encoding="utf-8"?>
<req>
  <title>test 123</title>
  <desc>任天堂次世代遊戲機Wii將於6月底登台</desc>
  <passwd>1127</passwd>
  <passwd_note>我家電話</passwd_note>
</req>

albumService/[guid]/categories
取得 user 相簿個人分類列表

範例 Request : http://wretch.yahooapis.com/v1/albumService/ZKWHF6P5LXDZSICROTM76OS4CI/categories

參數名稱	是否必填	預設值	說明
guid	是

albumService/[guid]/album/[album_id]
取得 user 某一本相簿之相片列表

範例 Request : http://wretch.yahooapis.com/v1/albumService/ZKWHF6P5LXDZSICROTM76OS4CI/album/1?start=1

參數名稱	是否必填	預設值	說明
guid	是
album_id	是
start	否	1	此值為頁碼, 每頁 show 20張相片

albumService/[guid]/album/[album_id]
在 user 的某一本相簿上傳一張照片 (POST)

範例 Request : http://wretch.yahooapis.com/v1/albumService/ZKWHF6P5LXDZSICROTM76OS4CI/album/1

參數名稱	是否必填	預設值	說明
guid	是
book_id	是
quality	否	1	縮圖品質: 最佳品質(0), 標準(1), 最省空間(2)
thumbtype	否	0	縮圖尺寸: 640x640(0), 800x800(1), 1024x1024(2), 原始尺寸(3)
upload_to_front	否	false	上傳後將照片放在最前面
exif_orientation	否	false	上傳後依照「相片資訊」自動調正

以下參數必須以 "XML的格式" 帶在 "Content" 中

參數名稱	是否必填	說明
title	是	相片標題
desc	否	相片描述
filename	是	相片檔名
content	是	照片內容經過base64 encode後的資料

Example:
<?xml version="1.0" encoding="utf-8"?>
<req>
  <title>test 123</title>
  <desc>遊戲機Wii</desc>
  <filename>test.jpg</filename>
  <content>#(*$&#*%</content>
</req>

albumService/[guid]/album/[album_id]/photo/[photo_id]
取得 user 的某一張相片的相關資訊

範例 Request : http://wretch.yahooapis.com/v1/albumService/ZKWHF6P5LXDZSICROTM76OS4CI/album/1/photo/1867326608

參數名稱	是否必填	預設值	說明
guid	是
album_id	是
photo_id	是

blogService/[guid]
取得 user 網誌服務狀態

範例 Request : http://wretch.yahooapis.com/v1/blogService/ZKWHF6P5LXDZSICROTM76OS4CI

參數名稱	是否必填	預設值	說明
guid	是

blogService/[guid]/categories
取得 user 網誌個人分類列表

範例 Request : http://wretch.yahooapis.com/v1/blogService/ZKWHF6P5LXDZSICROTM76OS4CI/categories

參數名稱	是否必填	預設值	說明
guid	是

blogService/[guid]/category/[category_id]
取得 user 網誌屬於某一個人分類之文章列表

範例 Request : http://wretch.yahooapis.com/v1/blogService/ZKWHF6P5LXDZSICROTM76OS4CI/category/2

參數名稱	是否必填	預設值	說明
guid	是
category_id	是
start	否	1	此值為頁碼, 每頁 show 500篇此分類之文章

blogService/[guid]/articles
取得 user 文章列表

範例 Request : http://wretch.yahooapis.com/v1/blogService/ZKWHF6P5LXDZSICROTM76OS4CI/articles?start=1

參數名稱	是否必填	預設值	說明
guid	是
start	否	1	此值為頁碼, 每頁 show 20篇文章

blogService/[guid]/articles
在 user 的 blog 發表文章 (POST)

範例 Request : http://wretch.yahooapis.com/v1/blogService/ZKWHF6P5LXDZSICROTM76OS4CI/articles

參數名稱	是否必填	預設值	說明
guid	是
year	是		發表時間 - 年
month	是		發表時間 - 月
day	是		發表時間 - 日
hour	是		發表時間 - 時
minute	是		發表時間 - 分
isCover	否	0	是否設為置頂文章: 是(1), 否(0)
allow_comment	否	1	允許回應: 不允許留言(0), 完全開放(1), 只允許會員留言(2), 只允許好友留言(3)
auto_correct	否	0	自動更正錯誤語法
ai	否	0	自動加
isCloak	否	0	文章保護方式: 完全開放(0), 完全隱藏(1), 密碼保護(2), 好友保護(3)
FriendGroup	否		好友保護, 允許閱讀之群組
class_id	是		全站分類
category_id	否		個人分類

以下參數必須以 "XML的格式" 帶在 "Content" 中

參數名稱	是否必填	說明
title	是	文章標題
content	否	文章內容
passwd	否	密碼保護之密碼
passwd_note	否	密碼保護之提示
tburl	否	本篇文章引用網址

Example:
<?xml version="1.0" encoding="utf-8"?>
<req>
  <title>test 123</title>
  <content>任天堂次世代遊戲機Wii將於6月底登台</content>
  <passwd>1123</passwd>
  <passwd_note>我家電話</passwd_note>
  <tburl>&id=123456</tburl>
</req>

blogService/[guid]/article/[article_id]
取得 user 的某篇文章資訊及文章的前三行預覽

範例 Request : http://wretch.yahooapis.com/v1/blogService/ZKWHF6P5LXDZSICROTM76OS4CI/article/5795695

參數名稱	是否必填	預設值	說明
guid	是
article_id	是

videoService/[guid]
取得 user 影音服務狀態

範例 Request : http://wretch.yahooapis.com/v1/videoService/ZKWHF6P5LXDZSICROTM76OS4CI

參數名稱	是否必填	預設值	說明
guid	是

videoService/[guid]/videoes
取得 user 影音列表

範例 Request : http://wretch.yahooapis.com/v1/videoService/ZKWHF6P5LXDZSICROTM76OS4CI/videoes

參數名稱	是否必填	預設值	說明
guid	是

videoService/[guid]/videoes
上傳一則影音 (POST)

範例 Request : http://wretch.yahooapis.com/v1/videoService/ZKWHF6P5LXDZSICROTM76OS4CI/videoes

參數名稱	是否必填	預設值	說明
guid	是
book_id	是		影片要上傳到哪一本相簿
quality	否	1	縮圖品質: 最佳品質(0), 標準(1), 最省空間(2)
category_id	否	0	個人分類
class_id	是		全站分類
isCloak	否	0	影片保護方式: 完全開放(0), 完全隱藏(1), 密碼保護(2)
allow_comment	否	0	回應權限: 完全開放回應(0), 僅開放會員回應(1), 僅開放好友回應(2), 不允許回應(3)

以下參數必須以 "XML的格式" 帶在 "Content" 中

參數名稱	是否必填	說明
title	是	影音標題
desc	否	影音描述
filename	是	影音檔名
content	是	影音內容經過base64 encode後的資料

Example:
<?xml version="1.0" encoding="utf-8"?>
<req>
  <title>test 123</title>
  <desc>遊戲機Wii</desc>
  <filename>test.avi</filename>
  <content>#(*$&#*%</content>
</req>