API包括什么內容?如何編寫API?
2012/3/12 10:04:09
網站建設軟件擁有一份優質的技術文檔是決定你的項目是否引人關注的重要因素。無論開源產品或面向開發者的產品,均是如此。你的設計文檔不應當僅僅直白地列出所有的終端函數和其參數。好的文檔應該是一整套有機的系統內容,能指引用戶通過文檔與API進行交互。你至少讓你的文檔包含以下幾個部分。參考索引、開發指南、開發教程。
1.加入人性化的因素
閱讀技術文檔枯燥乏味,自然不像坐過山車那樣緊張刺激。不過,你至少可以通過加入一些人性化的因素,或者開開玩笑。給你的例子中的變量其一些好玩兒的名字吧,別老是把函數名稱叫什么foo之類的,好讓你的讀者有煥然一新的感覺。至少,這可以保證你的讀者不會讀著讀著就睡過去。
3.減少點擊次數
開發者痛恨點擊鼠標,這已經不是什么秘密了。千萬別把你的文檔分散在數以萬計的頁面當中。盡量把相關的主題都放到一個頁面里。我們非常贊成使用“單頁面大指南”的組織形式(鏈接),這種形式不僅能讓用戶縱覽全局,僅僅通過一個導航欄就能進入他們感興趣的任意主題,另外還有一個好處是:用戶在進行搜索的時候,僅僅搜索當前頁面,就能涵蓋查找所有的內容。
4.不要在例子中包含抽象概念
你可以爭辯說,我的API本身就是個抽象體,抽象就是它的特點。然而,當你在教會開發者如何使用的過程中,還是能不抽象就不抽象比較好。在你的文檔中盡可能地舉現實中的例子吧。沒有哪個開發者會抱怨你舉例太多的。實際上,這種做法能顯著地縮短開發者理解你產品的時間。對此,我們的網站里甚至給出一個代碼樣例加以解釋。
5.支持多種編程語言
我們生活在一個多語言的世界。如果可能的話,為你的API提供各種編程語言版本的樣例程序,只要的API支持這些語言。多數時候,多語言的工作都是由客戶端庫來完成的。要知道,開發者要想掌握一套API,離開他們熟悉的編程語言,是很難想象的。MailGun’sAPI為此做出了良好的榜樣。它提供了curl,Ruby,Python,Java,C#和PHP等多個版本供開發者選擇。
6.包含適當的快速指南
萬事開頭難,開發者學習一套全新的API,不得不重新適應其全新的思維方式,學習代價高昂。對于這個問題的解決辦法是:通過快速指南來引導開發者。快速指南的目的是讓用戶用最小的代價學習如何利用你提供的API干一些小事。僅此而已。一旦用戶完成了快速指南,他們就對自己有了信心,并能向更加深入的主題邁進。
7.提供樣例應用
在學習結束的時候,開發者希望能看到關于項目產品應用的大致藍圖。達到這一目的最好的辦法,莫過于提供可運行的樣例應用。我發現,應用程序代碼是將API運行機理和系統整合融會貫通最好的辦法。samplecodeinApple’siOSDeveloperLibrary則是這方面做得很好的,它包含了詳盡的iOS樣例程序,并按主題一一分類。
8.絕不放過任何邊界情況
使用API開發應用,所能遭遇的最糟糕的情況,莫過于你發現了一個文檔中沒有提到的錯誤。如果你遇到這種情況,就意味著你不能確認究竟是你的程序出了錯,還是你對API的理解出了錯。因此,參考索引中必須包含每種假設可能造成的邊界情況,不論是顯示的還是隱式的。花點兒時間在這個上面,絕對能起到事半功倍的效果。
返回列表
返回首頁
主站蜘蛛池模板:
永久免费无内鬼放心开车|
97视频免费在线|
思思久久99热只有频精品66|
久草免费在线观看视频|
欧美精品久久久久久久自慰|
免费看一毛一级毛片视频|
色聚网久久综合|
国产成人免费片在线观看
|
japanese国产在线观看|
捏揉舔水插按摩师|
久久精品国产亚洲av麻豆色欲|
欧美多人野外伦交|
亚洲精品午夜国产va久久成人|
精品国产污污免费网站入口|
国产三级放荡的护士|
国产97在线观看|
国产精品久久久久国产精品三级
|
亚洲av无码之日韩精品|
欧美污视频网站|
亚洲黄色中文字幕|
真实国产乱人伦在线视频播放|
啊轻点灬大ji巴太粗太长h
|
美女大胸又爽又黄网站|
国产乱理伦片在线观看播放
|
成年性生交大片免费看|
久久国产小视频|
日韩美女片视频|
亚洲中文精品久久久久久不卡|
欧美精品一区二区久久|
亚洲黄色中文字幕|
男人j桶进女人p无遮挡在线观看|
农民人伦一区二区三区|
美女扒开尿囗给男生桶爽|
国产一区二区福利|
草莓视频成人在线观看|
国产喷水女王在线播放|
91成年人免费视频|
国产欧美在线一区二区三区
|
日本人内谢69xxxx|
久久人人爽人人爽人人片AV超碰|
日韩影片在线观看|