Github API v3 介紹文件

阿新 • • 發佈：2020-11-29

對於常用Github的使用者來說，經常有一些自動化的需求。比如我的需求是定時備份Github的issues和comments到本地。以下為Github的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通過許可權認證

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

作為url中的引數明文傳輸：

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

作為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
無傳輸資料