基本訪問路徑 (Root Endpoints)

一開始讀文檔的時候咆畏，照著它的事例直接在命令行里curl烫映，或者在InSomnia或Postman軟件里訪問兽间，都完美顯示200狀態(tài)茫叭。可是一旦把鏈接里改寫成自己的用戶名就各種顯示404無頁面负懦。還以為是授權(quán)問題，然后在頁頭HEADER中按照各種方式試了username和token密鑰柏腻，都沒用還是404纸厉。結(jié)果發(fā)現(xiàn)，原來不是方法的問題五嫂，純粹是鏈接地址沒寫對颗品！
實際上只是讀取的話，完全不用任何授權(quán)，可以在命令行抛猫、Insomnia蟆盹、網(wǎng)頁等各種情況下直接輸入鏈接訪問任何人的所有公開信息。
然后對照官方路徑列表Root Endpoints得到的鏈接闺金，好像怎么訪問都不對逾滥。反而在Stackoverflow中看到的一個鏈接，順藤摸瓜自己發(fā)現(xiàn)了各種正確的訪問路徑败匹，總結(jié)如下：

• 首先寨昙！訪問的鏈接最后不能有/。如https://api.github.com/users/solomonxie是可以訪問到我個人信息的掀亩，但是https://api.github.com/users/solomonxie/就不行了舔哪，唯一不同是多了一個/.
• 其次！不同于一般URL訪問槽棍，GIthub的API訪問鏈接是區(qū)分大小寫的捉蚤！
• 個人主要信息。 https://api.github.com/users/用戶名,得到數(shù)據(jù)如下圖：

• 個人所有repo炼七。https://api.github.com/users/用戶名/repos缆巧。會得到一個repo的JSON格式列表。
• repo詳細信息豌拙。https://api.github.com/repos/用戶名/倉庫名陕悬。repo的路徑就開始和個人信息不同了。
• 獲取某個repo的內(nèi)容列表按傅。https://api.github.com/repos/solomonxie/gists/contents捉超，注意這只會返回根目錄的內(nèi)容。
• 獲取repo中子目錄的內(nèi)容列表唯绍。https://api.github.com/repos/solomonxie/gists/contents/目錄名拼岳。一定要注意這里一定要完全遵循原文件名的大小寫，否則無法獲得信息况芒。如果是更深層的內(nèi)容裂问，則在鏈接列按照順序逐級寫上目錄名稱。
• 獲取repo中某文件信息（不包括內(nèi)容）牛柒。https://api.github.com/repos/solomonxie/gists/contents/文件路徑堪簿。文件路徑是文件的完整路徑，區(qū)分大小寫皮壁。只會返回文件基本信息椭更。
• 獲取某文件的原始內(nèi)容（Raw）。1. 通過上面的文件信息中提取download_url這條鏈接蛾魄，就能獲取它的原始內(nèi)容了虑瀑。2. 或者直接訪問：https://raw.githubusercontent.com/用戶名/倉庫名/分支名/文件路徑
• repo中所有的commits列表湿滓。https://api.github.com/repos/用戶名/倉庫名/commits。
• 某一條commit詳情舌狗。https://api.github.com/repos/用戶名/倉庫名/commits/某一條commit的SHA
• issues列表叽奥。https://api.github.com/repos/用戶名/倉庫名/issues。
• 某條issue詳情痛侍。https://api.github.com/repos/用戶名/倉庫名/issues/序號朝氓。issues都是以1,2,3這樣的序列排號的。
• 某issue中的comments列表主届。https://api.github.com/repos/用戶名/倉庫名/issues/序號/comments赵哲。
• 某comment詳情。https://api.github.com/repos/用戶名/倉庫名/issues/comments/評論詳情的ID君丁。其中評論ID是從issues列表中獲得的枫夺。

查詢參數(shù) (Parameters)

如果在上面基本鏈接中加入查詢條件，那么返回的數(shù)據(jù)就是filtered绘闷，過濾了的橡庞。比如要求只返回正在開放的issues，或者讓列表數(shù)據(jù)分頁顯示印蔗。常用如下：

• 分頁功能扒最。格式是?page=頁數(shù)&per_page=每頁包含數(shù)量。

如https://api.github.com/users/solomonxie/repos?page=2&per_page=3

• issues狀態(tài)喻鳄。格式是?state=狀態(tài)。

如https://api.github.com/repos/solomonxie/solomonxie.github.io/issues?state=closed

權(quán)限認證 Authentication

首先需要知道都是确封，到此為止之前所有都查詢都是不需要任何權(quán)限的除呵，給個地址就返回數(shù)據(jù)，全公開爪喘。
但是創(chuàng)建文件颜曾、更新、刪除等就是必須用自己的賬號"登錄"才能實現(xiàn)的秉剑。所以為了下面的增刪改做準備泛豪，需要先看一下權(quán)限問題。
官網(wǎng)雖然寫的很簡答侦鹏，不過如果不熟悉API的話還是不能馬上就理解诡曙。

常用的認證方法有三種，Basic authentication, OAuth2 token, OAuth2 key/secret
三種方法效果一樣略水，但是各有其特點和方便之處价卤。選哪種就要看自己哪種方便了。

認證方法一：Basic authentication

這種最簡單渊涝，如果是用curl的話慎璧，就：

curl -u "用戶名:密碼" https://api.github.com

如果是用Insomnia等api調(diào)試工具的話床嫌，直接在Auth選項欄里選Basic Auth，然后填上用戶名密碼即可胸私。

認證方法二：OAuth2 token

關(guān)于token

這種token方式厌处，說實話如果不是操作過API或深度了解REST的話，是很難理解的東西岁疼。
說白了就是第二個密碼阔涉，你既不用到處泄露自己的用戶名密碼，又可以專門給這個"第二密碼"設(shè)置不同需要的權(quán)限五续，如有的只可讀有的還可以寫等洒敏。而且這個“第二密碼”是既包括用戶名又包括密碼功能的，全站只此一個絕對不會和別人重復(fù)疙驾。初次之外凶伙，你還可以設(shè)置很多個token，也就是第三它碎、第四函荣、第五...密碼。很方便扳肛。

設(shè)置token方法

就位于github個人賬號設(shè)置->開發(fā)者設(shè)置->個人token里傻挂。創(chuàng)建一個新token時，可以選擇具體的權(quán)限挖息，創(chuàng)建成功時一定要復(fù)制到本地哪里保存金拒，只會讓你看見一次，如果忘記的話就需要重新生成（其實丟了也不算麻煩）套腹。

另外绪抛！注意：

token字符串不能存儲在github的repo中，經(jīng)過測試电禀，一旦提交的文件中包含這個token字符串幢码，那么github就會自動刪除這個token -_-! 我用了很久才明白過來，創(chuàng)建的Personal Access Token總是自動消失尖飞，還以為是有時限的症副。

用token通過權(quán)限認證

有兩種傳送方法，哪種都可以：

1. 作為url中的參數(shù)明文傳輸：

curl https://api.github.com/?access_token=OAUTH-TOKEN

1. 作為header中的參數(shù)傳輸：

curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com

如果不是用curl而是Insomnia測試的話政基，和上面basic auth是大同小異的贞铣，很容易操作就不復(fù)述了。
到此為止沮明，權(quán)限認證就算搞清了咕娄，而且也實際驗證過有效了。強烈建議用insomnia工具操作珊擂，有GUI界面方便理解圣勒，成功后再轉(zhuǎn)為curl或python等程序語言费变。

認證方法三：OAuth2 key/secret

這個是除了Personal Access Token之外的另一種好用的方法，即創(chuàng)建自己的OAuth app圣贸，然后得到一對client_id和client_secret挚歧。如下：

得到這兩個值之后，直接在訪問任何api的url連接后面顯性加上這兩個參數(shù)即可完成認證吁峻，如：
https://api.github.com/users/yourusername?client_id=YOUR-CLIENT-ID&client_secret=YOUR-CLIENT-SECRET
但是：

目前這種認證方式不支持查詢以外的操作滑负，也就是只能GET獲取某些api信息，不能執(zhí)行request里的任何PUT/PATCH/DELETE操作用含。

創(chuàng)建新文件 Create content

Contents操作 官方文檔

• 傳輸方法：PUT
• 訪問路徑：https://api.github.com/repos/用戶名/倉庫名/contents/文件路徑
• JSON格式：

{
  "message": "commit from INSOMNIA",
  "content": "bXkgbmV3IGZpbGUgY29udGVudHM="
}

• 注意：1.必須添加權(quán)限驗證（上面有寫） 2. 數(shù)據(jù)傳送格式選擇JSON 3. 文件內(nèi)容必須是把文件整體轉(zhuǎn)為Base64字符串再存到JSON變量中 4. 文件路徑中如果有不存在的文件夾矮慕，則會自動創(chuàng)建

起初不管怎么嘗試都一直報同樣都錯誤，400 Invalid JSON啄骇，如下圖：

最后發(fā)現(xiàn)原來是犯了很小很小都錯誤才導(dǎo)致如此：

原來痴鳄，我的token看似是正常的，唯獨錯誤的是缸夹，多了一個空行痪寻！也就是說，標(biāo)明都是invalid JSON虽惭，結(jié)果沒注意竟然是invalid Token!

增加文件成功后返回的消息：

更新文件 Update content

主要這幾點： 1. 傳送方式用PUT 和創(chuàng)建文件一樣 2. 需要權(quán)限驗證橡类，3. 傳輸內(nèi)容數(shù)據(jù)用JSON 4. 需要指定該文件的SHA碼 4. 路徑和訪問content時一樣 5. 文件內(nèi)容必須是把文件整體轉(zhuǎn)為Base64字符串再存到JSON變量中

• 傳輸方法：PUT
• 訪問路徑：https://api.github.com/repos/用戶名/倉庫名/contents/文件路徑
• JSON格式：

{
  "message": "update from INSOMNIA",
  "content": "Y3JlYXRlIGZpbGUgZnJvbSBJTlNPTU5JQQoKSXQncyB1cGRhdGVkISEhCgpJdCdzIHVwZGF0ZWQgYWdhaW4hIQ==",
  "sha": "57642f5283c98f6ffa75d65e2bf49d05042b4a6d"
}

• 注意：必須指定該文件的SHA碼，相當(dāng)于文件的ID芽唇。

SHA雖然是對文件的唯一識別碼顾画，相當(dāng)于ID，但是它是會隨著文件內(nèi)容變化而變化的匆笤！所以必須每次都重新獲取才行研侣。

至于獲取方式，驗證后發(fā)現(xiàn)疚膊，目前最靠譜的是用前面的get content獲取到該文件的信息义辕，然后里面找到sha虾标。

對上傳時的JSON格式另有要求寓盗，如果沒有按照要求把必填項輸入，則會出現(xiàn)422錯誤信息：

或者如果用錯了SHA璧函，會出現(xiàn)409錯誤消息：

如果正確傳送傀蚌，就會顯示200完成更新：

刪除文件 Delete content

• 傳輸方法：DELETE
• 訪問路徑：https://api.github.com/repos/用戶名/倉庫名/contents/文件路徑
• JSON格式：

{
  "message": "delete a file",
  "sha": "46d2b1f2ef54669a974165d0b37979e9adba1ab2"
}

刪除成功后，會返回200消息：

增刪改issues

如果做過了上面文件的增刪改蘸吓，這里大同小異善炫，不同的訪問路徑和JSON的格式而已。唯一不同的是库继，issues是不用把內(nèi)容轉(zhuǎn)為Base64碼的箩艺。

參考鏈接：github官方文檔

增加一條issue

• 傳輸方法：POST
• 訪問路徑：https://api.github.com/repos/用戶名/倉庫名/issues
• JSON格式：

{
  "title": "Creating issue from API",
  "body": "Posting a issue from Insomnia"
}

• 注意：issue的數(shù)據(jù)里面是可以加label窜醉，milestone和assignees的。但是必須注意milestone和assignees必須是已有的名次完全對應(yīng)才行艺谆，否則無法完成創(chuàng)建榨惰。

更改某條issue

• 傳輸方法：PATCH
• 訪問路徑：https://api.github.com/repos/用戶名/倉庫名/issues/序號
• JSON格式：

{
  "title": "Creating issue from API ---updated",
  "body": "Posting a issue from Insomnia \n\n Updated from insomnia.",
  "state": "open"
}

• 注意：如果JSON中加入空白的labels或assignees，如"labels": []静汤，作用就是清空所有的標(biāo)簽和相關(guān)人琅催。

鎖住某條issue

不允許別人評論（自己可以）

1.png

• 傳輸方法：PUT
• 訪問路徑：https://api.github.com/repos/用戶名/倉庫名/issues/序號/lock
• JSON格式：

{
  "locked": true,
  "active_lock_reason": "too heated"
}

• 注意：active_lock_reason只能有4種值可選：off-topic, too heated, resolved, spam，否則報錯虫给。

另外藤抡，成功鎖住，會返回204 No Content信息抹估。

解鎖某條issue

• 傳輸方法：DELETE
• 訪問路徑：https://api.github.com/repos/用戶名/倉庫名/issues/序號/lock
• 無JSON傳輸

增刪改comments

參考官方文檔

增加comment

• 傳輸方法：POST
• 訪問路徑：https://api.github.com/repos/用戶名/倉庫名/issues/序號/comments
• JSON格式：

{
  "body": "Create a comment from API"
}

更改comment

• 傳輸方法：PATCH
• 訪問路徑：https://api.github.com/repos/用戶名/倉庫名/issues/comments/評論ID
• JSON格式：

{
  "body": "Create a comment from API \n\n----Updated"
}

• 注意：地址中缠黍，issues后不用序號了，因為可以通過唯一的評論ID追查到棋蚌。查看評論ID的方法嫁佳，直接在上面查詢鏈接中找。

刪除comment

• 傳輸方法：DELETE
• 訪問路徑：https://api.github.com/repos/用戶名/倉庫名/issues/comments/評論ID
• 無傳輸數(shù)據(jù)