基本訪問路徑 (Root Endpoints)

一開始讀文檔的時(shí)候，照著它的事例直接在命令行里curl，或者在InSomnia或Postman軟件里訪問，都完美顯示200狀態(tài)?？墒且坏┌焰溄永锔膶懗勺约旱挠脩裘透鞣N顯示404無頁面。還以為是授權(quán)問題，然后在頁頭HEADER中按照各種方式試了username和token密鑰，都沒用還是404。結(jié)果發(fā)現(xiàn)，原來不是方法的問題，純粹是鏈接地址沒寫對！
實(shí)際上只是讀取的話，完全不用任何授權(quán)，可以在命令行、Insomnia、網(wǎng)頁等各種情況下直接輸入鏈接訪問任何人的所有公開信息。
然后對照官方路徑列表Root Endpoints得到的鏈接，好像怎么訪問都不對。反而在Stackoverflow中看到的一個(gè)鏈接，順藤摸瓜自己發(fā)現(xiàn)了各種正確的訪問路徑，總結(jié)如下：

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

• 個(gè)人所有repo。https://api.github.com/users/用戶名/repos。會(huì)得到一個(gè)repo的JSON格式列表。
• repo詳細(xì)信息。https://api.github.com/repos/用戶名/倉庫名。repo的路徑就開始和個(gè)人信息不同了。
• 獲取某個(gè)repo的內(nèi)容列表。https://api.github.com/repos/solomonxie/gists/contents，注意這只會(huì)返回根目錄的內(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ū)分大小寫。只會(huì)返回文件基本信息。
• 獲取某文件的原始內(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)限認(rèn)證 Authentication

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

常用的認(rèn)證方法有三種，Basic authentication, OAuth2 token, OAuth2 key/secret
三種方法效果一樣，但是各有其特點(diǎn)和方便之處。選哪種就要看自己哪種方便了。

認(rèn)證方法一：Basic authentication

這種最簡單，如果是用curl的話，就：

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

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

認(rèn)證方法二：OAuth2 token

關(guān)于token

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

設(shè)置token方法

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

另外！注意：

token字符串不能存儲(chǔ)在github的repo中，經(jīng)過測試，一旦提交的文件中包含這個(gè)token字符串，那么github就會(huì)自動(dòng)刪除這個(gè)token -_-! 我用了很久才明白過來，創(chuàng)建的Personal Access Token總是自動(dòng)消失，還以為是有時(shí)限的。

用token通過權(quán)限認(rè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)限認(rèn)證就算搞清了，而且也實(shí)際驗(yàn)證過有效了。強(qiáng)烈建議用insomnia工具操作，有GUI界面方便理解，成功后再轉(zhuǎn)為curl或python等程序語言。

認(rèn)證方法三：OAuth2 key/secret

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

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

目前這種認(rèn)證方式不支持查詢以外的操作，也就是只能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)限驗(yàn)證（上面有寫） 2. 數(shù)據(jù)傳送格式選擇JSON 3. 文件內(nèi)容必須是把文件整體轉(zhuǎn)為Base64字符串再存到JSON變量中 4. 文件路徑中如果有不存在的文件夾，則會(huì)自動(dòng)創(chuàng)建

起初不管怎么嘗試都一直報(bào)同樣都錯(cuò)誤，400 Invalid JSON，如下圖：

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

原來，我的token看似是正常的，唯獨(dú)錯(cuò)誤的是，多了一個(gè)空行！也就是說，標(biāo)明都是invalid JSON，結(jié)果沒注意竟然是invalid Token!

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

更新文件 Update content

主要這幾點(diǎn)： 1. 傳送方式用PUT 和創(chuàng)建文件一樣 2. 需要權(quán)限驗(yàn)證，3. 傳輸內(nèi)容數(shù)據(jù)用JSON 4. 需要指定該文件的SHA碼 4. 路徑和訪問content時(shí)一樣 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，但是它是會(huì)隨著文件內(nèi)容變化而變化的！所以必須每次都重新獲取才行。

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

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

或者如果用錯(cuò)了SHA，會(huì)出現(xiàn)409錯(cuò)誤消息：

如果正確傳送，就會(huì)顯示200完成更新：

刪除文件 Delete content

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

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

刪除成功后，會(huì)返回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，否則報(bào)錯(cuò)。

另外，成功鎖住，會(huì)返回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后不用序號了，因?yàn)榭梢酝ㄟ^唯一的評論ID追查到。查看評論ID的方法，直接在上面查詢鏈接中找。

刪除comment

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