Github API v3 介紹文檔

對於常用Github的用戶來說，經常有一些自動化的需求。比如我的需求是定時備份Github的issues和comments到本地。以下為Github的API的使用參考。

v3版API的文檔鏈接
v3版API的官方教程

基本訪問路徑 (Root Endpoints)

一開始讀文檔的時候，照着它的事例直接在命令行里curl，或者在InSomnia或Postman軟件里訪問，都完美顯示200狀態。可是一旦把鏈接里改寫成自己的用戶名就各種顯示404無頁面。還以為是授權問題，然后在頁頭HEADER中按照各種方式試了username和token密鑰，都沒用還是404。結果發現，原來不是方法的問題，純粹是鏈接地址沒寫對！
實際上只是讀取的話，完全不用任何授權，可以在命令行、Insomnia、網頁等各種情況下直接輸入鏈接訪問任何人的所有公開信息。
然后對照官方路徑列表Root Endpoints得到的鏈接，好像怎么訪問都不對。反而在Stackoverflow中看到的一個鏈接，順藤摸瓜自己發現了各種正確的訪問路徑，總結如下：

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

• 個人所有repo。https://api.github.com/users/用戶名/repos。會得到一個repo的JSON格式列表。
• repo詳細信息。https://api.github.com/repos/用戶名/倉庫名。repo的路徑就開始和個人信息不同了。
• 獲取某個repo的內容列表。https://api.github.com/repos/solomonxie/gists/contents，注意這只會返回根目錄的內容。
• 獲取repo中子目錄的內容列表。https://api.github.com/repos/solomonxie/gists/contents/目錄名。一定要注意這里一定要完全遵循原文件名的大小寫，否則無法獲得信息。如果是更深層的內容，則在鏈接列按照順序逐級寫上目錄名稱。
• 獲取repo中某文件信息（不包括內容）。https://api.github.com/repos/solomonxie/gists/contents/文件路徑。文件路徑是文件的完整路徑，區分大小寫。只會返回文件基本信息。
• 獲取某文件的原始內容（Raw）。1. 通過上面的文件信息中提取download_url這條鏈接，就能獲取它的原始內容了。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列表中獲得的。

查詢參數 (Parameters)

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

• 分頁功能。格式是?page=頁數&per_page=每頁包含數量。

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

• issues狀態。格式是?state=狀態。

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

權限認證 Authentication

首先需要知道都是，到此為止之前所有都查詢都是不需要任何權限的，給個地址就返回數據，全公開。
但是創建文件、更新、刪除等就是必須用自己的賬號"登錄"才能實現的。所以為了下面的增刪改做准備，需要先看一下權限問題。
官網雖然寫的很簡答，不過如果不熟悉API的話還是不能馬上就理解。

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

認證方法一：Basic authentication

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

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

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

認證方法二：OAuth2 token

關於token

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

設置token方法

就位於github個人賬號設置->開發者設置->個人token里。創建一個新token時，可以選擇具體的權限，創建成功時一定要復制到本地哪里保存，只會讓你看見一次，如果忘記的話就需要重新生成（其實丟了也不算麻煩）。

另外！注意：

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

用token通過權限認證

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

1. 作為url中的參數明文傳輸：

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

1. 作為header中的參數傳輸：

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

如果不是用curl而是Insomnia測試的話，和上面basic auth是大同小異的，很容易操作就不復述了。
到此為止，權限認證就算搞清了，而且也實際驗證過有效了。強烈建議用insomnia工具操作，有GUI界面方便理解，成功后再轉為curl或python等程序語言。

認證方法三：OAuth2 key/secret

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


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

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

創建新文件 Create content

Contents操作 官方文檔

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

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

JSON填寫如下圖：

• 注意：1.必須添加權限驗證（上面有寫） 2. 數據傳送格式選擇JSON 3. 文件內容必須是把文件整體轉為Base64字符串再存到JSON變量中 4. 文件路徑中如果有不存在的文件夾，則會自動創建

起初不管怎么嘗試都一直報同樣都錯誤，400 Invalid JSON，如下圖：
[圖片上傳失敗...(image-884e71-1527903120996)]

最后發現原來是犯了很小很小都錯誤才導致如此：

原來，我的token看似是正常的，唯獨錯誤的是，多了一個空行！也就是說，標明都是invalid JSON，結果沒注意竟然是invalid Token!

正確的token的處理模式是：token中間有空格

Authorization:token c092xxxxxx    

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

更新文件 Update content

主要這幾點： 1. 傳送方式用PUT 和創建文件一樣 2. 需要權限驗證，3. 傳輸內容數據用JSON 4. 需要指定該文件的SHA碼 4. 路徑和訪問content時一樣 5. 文件內容必須是把文件整體轉為Base64字符串再存到JSON變量中

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

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

• 注意：必須指定該文件的SHA碼，相當於文件的ID。

SHA雖然是對文件的唯一識別碼，相當於ID，但是它是會隨着文件內容變化而變化的！所以必須每次都重新獲取才行。

至於獲取方式，驗證后發現，目前最靠譜的是用前面的get content獲取到該文件的信息，然后里面找到sha。

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

或者如果用錯了SHA，會出現409錯誤消息：

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

刪除文件 Delete content

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

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

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

增刪改issues

如果做過了上面文件的增刪改，這里大同小異，不同的訪問路徑和JSON的格式而已。唯一不同的是，issues是不用把內容轉為Base64碼的。

參考鏈接：github官方文檔

增加一條issue

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

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

• 注意：issue的數據里面是可以加label，milestone和assignees的。但是必須注意milestone和assignees必須是已有的名次完全對應才行，否則無法完成創建。

更改某條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": []，作用就是清空所有的標簽和相關人。

鎖住某條issue

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

• 傳輸方法：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
• 無傳輸數據