Wretch API 文件 - Version 1.0 Preview

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 個人資料

範例 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    

範例 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>

videoService/[guid]/video/[video_id]
取得 user 某則影音及該則影音之相關資訊

範例 Request : http://wretch.yahooapis.com/v1/videoService/ZKWHF6P5LXDZSICROTM76OS4CI/video/4875696?start=1

參數名稱 是否必填 預設值 說明
guid    
start 1 此值為頁碼, 每頁 show 30 則影音

videoService/[guid]/categories
取得 user 影音個人分類列表

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

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

videoService/[guid]/category/[category_id]
取得 user 某個影音分類下的影音列表

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

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

friendService/[guid]
取得 user 好友服務狀態

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

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

friendService/[guid]/friends
取得 user 的好友列表

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

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

friendService/[guid]/friendGroups
取得 user 的好友群組列表

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

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

friendService/[guid]/friendGroup/[group_id]
取得 user 的某一好友群組列表

範例 Request : http://wretch.yahooapis.com/v1/friendService/ZKWHF6P5LXDZSICROTM76OS4CI/friendGroup/2

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

friendService/[guid]/mutualFriends
取得與 user 互加好友列表

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

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

friendService/[guid]/reverseFriends
取得加此 user 為好友之列表

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

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

diguService/[guid]
取得 user digu 的服務狀態

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

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

diguService/[guid]/messages
發表(回覆) digu 訊息 (POST)

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

參數名稱 是否必填 預設值 說明
guid    
digu_id 0 digu 訊息編號, 若值為0, 表示是對 userid 嘀咕; 若值為非0之值, 表示是對 userid 的某則嘀咕回應

以下參數必須以 "XML的格式" 帶在 "Content" 中
參數名稱 是否必填 預設值 說明
userid  
digu_mesg   digu 訊息內容

Example:
<?xml version="1.0" encoding="utf-8"?>
<req>
  <userid>wretchoffice</userid>
  <digu_mesg>test 123</digu_mesg>
</req>

diguService/[guid]/message/[msg_id]
取得 user 所發表的某則 digu 訊息

範例 Request : http://wretch.yahooapis.com/v1/diguService/ZKWHF6P5LXDZSICROTM76OS4CI/message/[msg_id]

參數名稱 是否必填 預設值 說明
guid    
msg_id   digu 訊息編號

diguService/[guid]/message/[msg_id]
刪除 user 所發表的 digu 訊息 (DELETE)

範例 Request : http://wretch.yahooapis.com/v1/diguService/ZKWHF6P5LXDZSICROTM76OS4CI/message/[msg_id]

參數名稱 是否必填 預設值 說明
guid    
msg_id   digu 訊息編號

diguService/[guid]/myDigus
取得 user 的 "我的嘀咕"

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

參數名稱 是否必填 預設值 說明
guid    
start 1 此值為頁碼, 每頁 show 10則digu, 最多可show至第10頁

diguService/[guid]/allDigus
取得 user 的 "一起嘀咕"

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

參數名稱 是否必填 預設值 說明
guid    
start 1 此值為頁碼, 每頁 show 10則digu, 最多可show至第10頁

diguService/[guid]/diguReplies
取得 user 的 "對我嘀咕"

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

參數名稱 是否必填 預設值 說明
guid    
start 1 此值為頁碼, 每頁 show 10則digu, 最多可show至第10頁

diguService/[guid]/followers
取得 user 的訂閱列表

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

參數名稱 是否必填 預設值 說明
guid    
start 1 此值為頁碼, 每頁 show 10 個 user

diguService/[guid]/followings
取得訂閱 user 的列表

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

參數名稱 是否必填 預設值 說明
guid    
start 1 此值為頁碼, 每頁 show 10 個 user

diguService/[guid]/subscriptions
訂閱 user 的嘀咕 (POST)

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

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

diguService/[guid]/subscription
取消訂閱 user 的嘀咕 (DELETE)

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

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

siteAlbumCategories
取得相簿全站分類列表

siteVideoCategories
取得影音全站分類列表

siteDiguAnnounces
取得 20 則全站最新嘀咕

工具與實作參考

  • ASTRA

    ASTRA 是一個 ActionScript 的 RIA 工具包,有許多由 Yahoo! 所開發的 Flash 與 Flex 的元件、函式庫、工具包、控制項,方便給 ActionScript 的開發者使用。

  • 設計模式

    常用模組的互動設計模式參考,提昇您網站的可用性。

  • 效能處理

    改進網站效能的實作原則,內容包含了實驗結果與測試工具,讓您可以依據這些實作原則建立起高效能的網站。

  • 網路安全

    網路安全的實作原則與規定,讓使用者相信您所撰寫的應用程式並受到保護。

  • YUI 使用者函式庫

    YUI 提供製作 Web 2.0 網站所需的 JavaScript 相關功能與控制項,更提供了 CSS 的解決方案。除了符合前端快速開發的要求,更是一個最專業、文件最齊全的函式庫。