separate project repositories API docs

1 files changed, 166 insertions, 0 deletions

diff --git a/doc/api/repositories.md b/doc/api/repositories.md
new file mode 100644
index 00000000000..487ad9b2718
--- /dev/null
+++ b/doc/api/repositories.md
@@ -0,0 +1,166 @@
+## Project repository branches
+
+Get a list of repository branches from a project, sorted by name alphabetically.
+
+```
+GET /projects/:id/repository/branches
+```
+
+Parameters:
+
++ `id` (required) - The ID or code name of a project
+
+```json
+[
+  {
+    "name": "master",
+    "commit": {
+      "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
+      "parents": [
+        {
+          "id": "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
+        }
+      ],
+      "tree": "46e82de44b1061621357f24c05515327f2795a95",
+      "message": "add projects API",
+      "author": {
+        "name": "John Smith",
+        "email": "john@example.com"
+      },
+      "committer": {
+        "name": "John Smith",
+        "email": "john@example.com"
+      },
+      "authored_date": "2012-06-27T05:51:39-07:00",
+      "committed_date": "2012-06-28T03:44:20-07:00"
+    }
+  }
+]
+```
+
+## Project repository branch
+
+Get a single project repository branch.
+
+```
+GET /projects/:id/repository/branches/:branch
+```
+
+Parameters:
+
++ `id` (required) - The ID or code name of a project
++ `branch` (required) - The name of the branch
+
+```json
+{
+  "name": "master",
+  "commit": {
+    "id": "7b5c3cc8be40ee161ae89a06bba6229da1032a0c",
+    "parents": [
+      {
+        "id": "4ad91d3c1144c406e50c7b33bae684bd6837faf8"
+      }
+    ],
+    "tree": "46e82de44b1061621357f24c05515327f2795a95",
+    "message": "add projects API",
+    "author": {
+      "name": "John Smith",
+      "email": "john@example.com"
+    },
+    "committer": {
+      "name": "John Smith",
+      "email": "john@example.com"
+    },
+    "authored_date": "2012-06-27T05:51:39-07:00",
+    "committed_date": "2012-06-28T03:44:20-07:00"
+  }
+}
+```
+
+## Project repository tags
+
+Get a list of repository tags from a project, sorted by name in reverse alphabetical order.
+
+```
+GET /projects/:id/repository/tags
+```
+
+Parameters:
+
++ `id` (required) - The ID or code name of a project
+
+```json
+[
+  {
+    "name": "v1.0.0",
+    "commit": {
+      "id": "2695effb5807a22ff3d138d593fd856244e155e7",
+      "parents": [
+
+      ],
+      "tree": "38017f2f189336fe4497e9d230c5bb1bf873f08d",
+      "message": "Initial commit",
+      "author": {
+        "name": "John Smith",
+        "email": "john@example.com"
+      },
+      "committer": {
+        "name": "Jack Smith",
+        "email": "jack@example.com"
+      },
+      "authored_date": "2012-05-28T04:42:42-07:00",
+      "committed_date": "2012-05-28T04:42:42-07:00"
+    }
+  }
+]
+```
+
+## Project repository commits
+
+Get a list of repository commits in a project.
+
+```
+GET /projects/:id/repository/commits
+```
+
+Parameters:
+
++ `id` (required) - The ID or code name of a project
++ `ref_name` (optional) - The name of a repository branch or tag
+
+```json
+[
+  {
+    "id": "ed899a2f4b50b4370feeea94676502b42383c746",
+    "short_id": "ed899a2f4b5",
+    "title": "Replace sanitize with escape once",
+    "author_name": "Dmitriy Zaporozhets",
+    "author_email": "dzaporozhets@sphereconsultinginc.com",
+    "created_at": "2012-09-20T11:50:22+03:00"
+  },
+  {
+    "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
+    "short_id": "6104942438c",
+    "title": "Sanitize for network graph",
+    "author_name": "randx",
+    "author_email": "dmitriy.zaporozhets@gmail.com",
+    "created_at": "2012-09-20T09:06:12+03:00"
+  }
+]
+```
+
+## Raw blob content
+
+Get the raw file contents for a file.
+
+```
+GET /projects/:id/repository/commits/:sha/blob
+```
+
+Parameters:
+
++ `id` (required) - The ID or code name of a project
++ `sha` (required) - The commit or branch name
++ `filepath` (required) - The path the file
+
+Will return the raw file contents.