使用開放的 API 作一個本身的小項目,是一個很好的學習方法。但好像開放的 API 選擇並很少。這裏給你們多一個選擇,簡單介紹一下維基百科使用的 MediaWiki API。php
先簡單介紹幾個容易混淆的概念。html
Wiki 是一種在網絡上開放且可供多人協同創做的超文本系統。Wiki 站點能夠由多人維護,不一樣人能夠對同一個主題進行拓展和探討。json
MediaWiki 是一個免費、開放的 Wiki 引擎,不少著名的 wiki 網站都採用這套系統。api
咱們常說的維基百科,通常是指 Wikipedia,它是基於 MediaWiki 的一個網絡百科全書。網絡
但要理解的是,除了 Wikipedia,還有不少別的 Wiki 站點。從這個角度考慮的話,維基(Wiki)也有多是指別的網站,不過 Wikipedia 太出名了,以致於不少人直接將 Wikipedia 等同於 Wiki。dom
在瞭解到維基百科的 API 是開放的以後,我就找到了官方的 API 文檔,但以我目前的水平,這個文檔幾乎徹底看不懂。在網上找了好久,但願能夠有一篇文章以中文看得懂的方式,告訴我這些 API 是怎麼用的,但很惋惜並無。學習
沒辦法,本身對着官方文檔琢磨了好久,勉強總結出一些比較經常使用的調用方法。但願本文可讓你對 MediaWiki 的內容獲取有一個大概的瞭解,讓你能用它作出本身的項目。優化
本文全部內容都來自如下官方文檔,若是能看懂,就不用再往下看啦。網站
爲了方便理解,下面的說明都會有例子,用的是「灰機wiki」的「冰與火之歌中文維基」站點,域名是 asoiaf.huijiwiki.com,並經過 api.php 訪問。固然,只要是基於 MediaWiki 的 Wiki 站點,下面說明都是適用的。
接口中的 action 用來指定請求相應的動做,他的可取值很是很是多。咱們這裏只考慮內容的獲取,不進行用戶管理、內容編輯等操做,因此只要知道一個值就好了,全部接口都是 action = query。query 就是表明獲取數據。
這個用來指定數據返回的格式,咱們統一用 JSON 格式,即 format = json。
但我在使用過程當中發現,返回的 JSON 數據不少都是用「*」號或者是數字做爲字段名的,解析起來很麻煩。這種狀況下能夠嘗試增長 formatversion = 2,讓返回的數據更正常一些,便於解析。
在 action = query 的狀況下,會增長一些可用的參數,其中 list 是比較經常使用的一個。list 的可選值也不少,下面是幾個我認爲比較經常使用的值。
在對一個站點還不是很瞭解的狀況下,咱們能夠先看一下它有哪些分類。list = allcategories 表明列舉出全部分類:
其中,aclimit 指定了返回的條目數量,默認值是 10,不能超過 500。
當數據存在下一頁的時候,返回的數據裏會有 continue 字段,好比:
continue: {
accontinue: "Castle_Black", continue: "-||" }
要獲取下一頁,把 accontinue 這個參數帶上就行:
如今咱們知道有哪些分類了,接下來想看一下某個分類下有哪些內容,就要用到 categorymembers,它用於列出指定分類中的全部頁面。分類名傳入 cmtitle,須要包括「Category:」這個前綴。
假如我想看一下「史塔克家族」有哪些頁面:
http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&list=categorymembers&cmtitle=Category:史塔克家族&cmlimit=50
這裏控制返回數量的是 cmlimit,獲取下一頁的是 cmcontinue。
要是我想給用戶一種新鮮感,每次在首頁隨機展現一些內容,list = random 是你須要的,它用於隨機返回一些內容:
rnlimit 控制返回的數量,默認是 1。同理,獲取下一頁要用 rncontinue。後面也是相似的。
這裏還有一個命名空間 NameSpace 的概念。當 rncontinue = 0 表明指定返回的是頁面,rncontinue = 6 是文件,rncontinue = 14 是分類,別的我尚未用到過。
搜索功能確定是少不了的,咱們用 list = search,將關鍵字傳給 srsearch 進行搜索。
搜索含有「史塔克」的頁面:
http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&list=search&srsearch=史塔克&srnamespace=0&srlimit=10
目前我用到的 list 取值就這些。下面講一下另外一個重要的參數。
若是是要獲取某個頁面的相關數據,就涉及到 prop 這個參數。它用來指定要獲取的數據類型,它的可選值也不少,下面也挑幾個經常使用的說。
這個用來獲取頁面所屬的全部分類,好比艾德·史塔克屬於史塔克家族,也屬於國王之手:
http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&prop=categories&titles=艾德·史塔克&cllimit=20
除了文字描述,圖片也是內容裏的一個重要信息,prop = images 用來獲取指定頁面的全部文件。雖然是 image,可是它能獲取到各類文件,包括視頻:
http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&prop=images&titles=艾德·史塔克&imlimit=50
prop = pageimages 也是用來獲取頁面圖片的,按個人理解,它是用來獲取頁面封面的。好比咱們獲取「艾德·史塔克」的封面:
http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&prop=pageimages&titles=艾德·史塔克&pithumbsize=500
pithumbsize 用來指定圖片的尺寸,默認只有 50 px。另外要注意,不是每一個頁面都是有封面的。
接下來是最重要的獲取頁面內容了。revisions 文檔解釋是用來獲取修訂版本信息的,能夠用來獲取最新的頁面數據。
我這樣來獲取「艾德·史塔克」的頁面數據:
http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&prop=revisions&titles=艾德·史塔克&rvprop=content&rvparse=true
rvprop = content 表示須要返回頁面的文本內容。rvparse = true 表示將文本內容解析爲 html,不然是純文本內容。
除了 content,rvprop 還有不少可選值,同時須要多種內容,能夠用「|」分隔。好比同時返回修訂時間戳、修訂的用戶及修訂內容,能夠這樣表示:rvprop=timestamp|user|content。
其實不少參數的取值都是支持使用「|」的,將多條數據一塊兒返回。好比咱們將上面提到的 prop 取值一次所有獲取到,能夠這樣調用:
http://asoiaf.huijiwiki.com/api.php?action=query&format=json&formatversion=2&prop=categories|images|pageimages|revisions&titles=艾德·史塔克&rvprop=timestamp|user|content&rvparse=true
上面介紹的這些只能算是接觸到 MediaWiki API 的一點皮毛而已,但我仍是花了些時間才總結出來的。想要有很深刻的瞭解,仍是要去研究一下官方文檔。
我用冰與火中文維基的接口寫了一個 Android App,叫「冰與火維基」,但還有一些沒優化好的地方,感興趣的能夠在這裏下載到。