前言
Gitlab作為一個開源、強大的分布式版本控制系統，已經成為互聯網公司、軟件開發公司的主流版本管理工具。使用過gitlab的同學都知道，想要提交一段代碼，可以通過git push提交到遠程倉庫，也可以直接在gitlab平臺上修改提交。然而上述兩種提交方式都是人工提交代碼，需要手動登錄gitlab或者在第一次commit的時候提供gitlab帳號和密碼。那么，假設有這么一個需求場景：我們開發了一個效率平臺，可以自動拉分支、自動提交代碼到遠程倉庫。這個需求該如何實現？其實很簡單，gitlab提供了一套完整的API，讓第三方平臺可以通過API自動創建帳號、自動提交代碼、自動拉分支，等等。API涉及到的功能非常全面，覆蓋了分支、tag、代碼提交、用戶、群組、項目等，基本上人工可以做的所有操作，都可以通過API自動實現。
身份認證
Gitlab的所有API都需要提供private_token參數進行用戶身份認證（除了用來獲得private_token的接口本身）。如果沒有提供或者提供的private_token不合法，API將會返回401錯誤碼。
{"message":"401 Unauthorized"}
private_token是用來代表用戶身份的字符串，和用戶是一一對應的關系，http請求中包含這個就可以免輸入用戶名和密碼。
獲得private_token的方式有兩種：
方法一：查看帳號設置（Profile Settings -> Account）。如下圖：
方法二：通過Session API獲得Gitlab提供了一個API獲取某個用戶對應的private_token，這樣就能把所有操作都完全自動化起來，也方便了Gitlab與其它系統/平臺打通。Session接口需要提供帳號密碼來進行身份認證。
API分類介紹
從功能上劃分，gitlab API可分為以下幾類：
會話（/session）
此類API只包含一個接口，接口的作用是提供用戶帳號（或者郵箱帳號）和密碼，獲得該用戶的private_token，后續所有的API都用此token做身份認證。? 因為這里的密碼是明文提供，所以為了安全起見，最好將gitlab服務部署為https，保證帳號信息不會被非法竊取。
用戶帳號（/users）
包括：
1. 查看單個用戶信息
2. 查看所有用戶信息
3. 查看當前認證用戶信息* 帳號的創建、修改、刪除、封禁（只有管理員有權限做此操作）
4. SSH Key增刪改查（非管理員只能操作自身的，管理員可以操作所有人）
5. 用戶郵箱增刪改查（非管理員只能操作自身的，管理員可以操作所有人）
群組（Group）和命名空間（Namespace）
Gitlab項目的權限控制是基于命名空間來做的。命名空間包括群組和用戶兩種。此類API包括命名空間的查詢、群組的增刪改查等。
項目（/projects）
主要包括：
1. 列出當前用戶有權限訪問的所有項目
2. 列出當前用戶擁有的（owned）所有項目
3. 列出當前用戶標星了(starred)的項目
4. 列出所有項目（只有管理員有權限做此操作）
5. 查看單個項目
6. 從新到舊列出某個項目的所有事件（events）
7. 創建、編輯、刪除有權限的項目
8. 項目成員操作
9. 項目hooks操作
10. 根據項目名搜索項目（模糊搜索）
分支（Branches）
主要包括：
1. 查看倉庫的單個、所有分支
2. 保護（protect）某個分支、去掉某個分支的保護(unprotect)
3. 創建、刪除分支
Tags
主要包括：
1. 查看倉庫所有tag
2. 創建、刪除tag
3. 創建、修改release
項目倉庫（Repositories）
主要包括：
1. 查看倉庫代碼目錄樹
2. 查看某個文件的明文文本
3. 對比不同分支、tag或者提交(commit)
4. 列出倉庫的所有提交人
倉庫代碼文件（Repository files）
提交代碼主要通過操作（CURD, Create, Update, Read, Delete）某個代碼文件來完成。和命令行不同的是，用API提交代碼時不會有版本沖突，因為它總是用新內容覆蓋掉當前文件的內容。
提交（commit）
包括：
1. 查詢提交
2. 查看提交的對比（diff）
3. 查詢提交的注釋（comment）
4. post某次提交的注釋
5. 查詢某次提交的狀態
代碼合并（merge）
即操作代碼合并，包括合并請求的查詢、提交等。
注釋（Notes, Comments）
注釋的增改查。
?項目快照（snippets）
查看、創建、修改、刪除一個或者多個項目快照。
?項目構建（Builds）
如果使用了gitlab的持續集成功能，可以通過操作構建的API來管理（CURD）所有構建。
一些不常用的功能
包括Issues, Labels, Milestones, Deploy Keys, System Hooks, Settings等的操作。
服務（services）
包括Asana, Assembla, Atlassian Bamboo CI, Buildkite, Campfire, Custom Issue Tracker, Drone CI, Emails on push, External Wiki, Flowdock, Gemnasium, GitLab CI, HipChat, Irker (IRC gateway), JIRAPivotalTracker, Pushover, Redmine, Slack, JetBrains TeamCity CI（再次感嘆gitlab服務的強大和全面）。因為都不是特別常用，所以這里不一一介紹，有需要可自行查閱API幫助文檔。
使用示例：拉分支
第一步：獲取private_token
代碼片段：
第二步：新建分支
代碼片段：
特別提示
token緩存
如果用戶沒有手動重置private_token，那么private_token是固定不變的，所以沒有必要每次都調API去獲取，而是可以將它緩存起來，以提升性能。當遇到API返回401 Unauthorized的情況時，再調Session接口重新獲取token并更新緩存。
Http請求方法
特別注意，gitlab api限制了請求的方法，一般查詢請求是GET，創建請求是POST，修改請求是PUT，刪除請求是DELETE，方法寫錯了api將返回405 Method Not Allowed錯誤。
幫助文檔
作為一個強大靠譜的服務，gitlab提供了API的幫助文檔，上面有注明所有API的使用簡單示例。
幫助文檔入口：{gitlab_host}/help/api/README.md；或者點擊主菜單“Help” -> 點擊Documentation底下的API進入，如圖所示：
最后
當前筆者正在研究gitlab的源碼，后續會分享更多的東西給大家，比如gitlab的api是如何實現的，是否存在安全或者效率的問題，應當如何改進等。
