Provides a read-only restful interface for accessing data from Git repositories (local to the server). Modeled off the GitHub API for compatibility (see http://developer.github.com/v3/).
Requires:
- Python 2.7
- Flask
- pygit2 (= 0.22.0), which itself requires libgit2 (= 0.22.0)
Optional:
- filemagic (= 1.6) (offers improved MIME-type guessing), which itself requires libmagic (= 5.11)
The restfulgit.app module is a valid WSGI application.
While the app can be run with python -m restfulgit.app -- this runs Flask in debug mode and should NOT be used in production.
Instead, the app can be run with any WSGI server, such as gunicorn (pip install gunicorn; gunicorn restfulgit.app)
(Note: If you haven't installed restfulgit into your Python environment, you may need to explicitly set PYTHONPATH when running the above commands.)
RestfulGit uses Flask's config system. See example_config.py for an example config file.
If the $RESTFULGIT_CONFIG environment variable is set, RestfulGit will assume its value is a config filepath and will attempt to load its config from that file.
If the variable is not set or the loading attempt fails, RestfulGit will then attempt to load its config from /etc/restfulgit.conf.py.
| Config parameter | Default value | Description |
|---|---|---|
| RESTFULGIT_REPO_BASE_PATH | (none) | Root path for Git repositories. Note: only repositories immediately under this path are currently supported. |
| RESTFULGIT_DEFAULT_COMMIT_LIST_LIMIT | 50 | Number of most recent commits to return by default from the "commits" API endpoint. |
| RESTFULGIT_ENABLE_CORS | False | Whether to enable cross-origin resource sharing (CORS) headers for the API endpoints. |
| RESTFULGIT_CORS_ALLOWED_HEADERS | [] (empty list) |
List of HTTP header names (strings) that are allowed be used by the client when making a CORS request. |
| RESTFULGIT_CORS_ALLOW_CREDENTIALS | False | Whether HTTP Cookies and HTTP Authentication information should be sent by the client when making a CORS request. |
| RESTFULGIT_CORS_MAX_AGE | 30 days | datetime.timedelta specifying how long the results of a CORS preflight request can be cached by clients. |
| RESTFULGIT_CORS_ALLOWED_ORIGIN | * (all origins) |
Which origin is allowed to access the API endpoints using CORS. |
--
All of these routes return JSON unless otherwise specified.
Retrieves a list of commit objects (in plumbing format):
GET /repos/:repo_key/git/commits/
optional: ?start_sha=:sha
optional: ?ref_name=:ref_name
optional: ?limit=:limit (default=50, or as specified by the config)
[
{
"sha": "f85df530d8413b0390364b291eb97d1cc5798dee",
"url": "http://localhost:5000/repos/restfulgit/git/commits/f85df530d8413b0390364b291eb97d1cc5798dee/",
"author": {
"date": "2013-05-20T23:11:30Z",
"name": "Rajiv Makhijani",
"email": "[email protected]"
},
"committer": {
"date": "2013-05-20T23:11:30Z",
"name": "Rajiv Makhijani",
"email": "[email protected]"
},
"tree": {
"url": "http://localhost:5000/repos/restfulgit/git/trees/4c392547aa3d644877f3b22e198a5caac99a69a3/",
"sha": "4c392547aa3d644877f3b22e198a5caac99a69a3"
},
"parents": [
{
"url": "http://localhost:5000/repos/restfulgit/git/commits/7b3f40ff9aba370a59732522420201b744297317/",
"sha": "7b3f40ff9aba370a59732522420201b744297317"
}
],
"message": "Renamed main api file, added production recommendation to README"
},
...
]Retrieves a specific commit object (plumbing format) given its SHA:
GET /repos/:repo_key/git/commits/:sha/
Retrieves a specific commit object (porcelain format) given a branch name, tag name, or commit SHA:
GET /repos/:repo_key/commits/:refspec/
{
"sha": "07b9bf1540305153ceeb4519a50b588c35a35464",
"url": "http://localhost:5000/repos/restfulgit/commits/07b9bf1540305153ceeb4519a50b588c35a35464/",
"files": [
{
"filename": "api.py",
"status": "added",
"sha": "ae9d90706c632c26023ce599ac96cb152673da7c",
"raw_url": "http://localhost:5000/repos/restfulgit/raw/07b9bf1540305153ceeb4519a50b588c35a35464/api.py",
"contents_url": "http://localhost:5000/repos/restfulgit/contents/api.py?ref=07b9bf1540305153ceeb4519a50b588c35a35464",
"changes": 179,
"additions": 179,
"deletions": 0,
"patch": ...,
}
],
"stats": {
"additions": 179,
"deletions": 0,
"total": 179
},
"author": {
"date": "2013-02-24T13:25:46Z",
"name": "Rajiv Makhijani",
"email": "[email protected]"
},
"committer": {
"date": "2013-02-24T13:25:46Z",
"name": "Rajiv Makhijani",
"email": "[email protected]"
},
"parents": [],
"commit": {
"committer": {
"date": "2013-02-24T13:25:46Z",
"name": "Rajiv Makhijani",
"email": "[email protected]"
},
"author": {
"date": "2013-02-24T13:25:46Z",
"name": "Rajiv Makhijani",
"email": "[email protected]"
},
"url": "http://localhost:5000/repos/restfulgit/git/commits/07b9bf1540305153ceeb4519a50b588c35a35464/",
"tree": {
"url": "http://localhost:5000/repos/restfulgit/git/trees/6ca22167185c31554aa6157306e68dfd612d6345/",
"sha": "6ca22167185c31554aa6157306e68dfd612d6345"
},
"sha": "07b9bf1540305153ceeb4519a50b588c35a35464",
"parents": [],
"message": "Initial support for read-only REST api for Git plumbing"
}
}Retrieves a diff of the changes in a given commit (specified by branch name, tag name, or commit SHA):
GET /repos/:repo_key/commit/:refspec.diff
Content-Type: text/x-diff; charset=utf-8
diff --git a/api.py b/api.py
new file mode 100644
index 0000000..ae9d907
--- /dev/null
+++ b/api.py
@@ -0,0 +1,179 @@
+from flask import Flask, url_for
...
Given two commits, retrieves as good a common ancestor commit as possible for a merge. If there is no common ancestor, returns null (and HTTP 200 OK).
GET /repos/<repo_key>/git/commits/<sha:left_sha>/merge-base/<sha:right_sha>/
{
"committer": {
"date": "2013-02-24T13:25:46Z",
"name": "Rajiv Makhijani",
"email": "[email protected]"
},
"author": {
"date": "2013-02-24T13:25:46Z",
"name": "Rajiv Makhijani",
"email": "[email protected]"
},
"url": "http://localhost:5000/repos/restfulgit/git/commits/07b9bf1540305153ceeb4519a50b588c35a35464/",
"tree": {
"url": "http://localhost:5000/repos/restfulgit/git/trees/6ca22167185c31554aa6157306e68dfd612d6345/",
"sha": "6ca22167185c31554aa6157306e68dfd612d6345"
},
"sha": "07b9bf1540305153ceeb4519a50b588c35a35464",
"parents": [],
"message": "Initial support for read-only REST api for Git plumbing"
}Retrieves a list of branches:
GET /repos/:repo_key/branches/
[
{
"name": "master",
"commit": {
"url": "http://localhost:5000/repos/restfulgit/commits/7ad9ae851a4491ab55042bccbab24fc8d740aaea/",
"sha": "7ad9ae851a4491ab55042bccbab24fc8d740aaea"
}
},
...
]Retrieves a specific branch object:
GET /repos/:repo_key/branches/:branch_name/
{
"name": "master",
"url": "http://localhost:5000/repos/restfulgit/branches/master/",
"commit": {
"sha": "dc745192fba83adc48361c36f73d0c7b6e060ed3",
"url": "http://localhost:5000/repos/restfulgit/commits/dc745192fba83adc48361c36f73d0c7b6e060ed3/",
"committer": {
"date": "2014-05-09T18:38:19Z",
"name": "Chris Rebert",
"email": "[email protected]"
},
"author": {
"date": "2014-05-09T18:38:19Z",
"name": "Chris Rebert",
"email": "[email protected]"
},
"parents": [
{
"sha": "6c1626a0d07e4bcfdbee4a11c898199a6f7d07b6",
"url": "http://localhost:5000/repos/restfulgit/commits/6c1626a0d07e4bcfdbee4a11c898199a6f7d07b6/"
}
],
"commit": {
"sha": "dc745192fba83adc48361c36f73d0c7b6e060ed3",
"url": "http://localhost:5000/repos/restfulgit/git/commits/dc745192fba83adc48361c36f73d0c7b6e060ed3/",
"committer": {
"date": "2014-05-09T18:38:19Z",
"name": "Chris Rebert",
"email": "[email protected]"
},
"author": {
"date": "2014-05-09T18:38:19Z",
"name": "Chris Rebert",
"email": "[email protected]"
},
"tree": {
"url": "http://localhost:5000/repos/restfulgit/git/trees/3c02cb0f836416718a76d853583c3aae37c1dff7/",
"sha": "3c02cb0f836416718a76d853583c3aae37c1dff7"
},
"parents": [
{
"url": "http://localhost:5000/repos/restfulgit/commits/6c1626a0d07e4bcfdbee4a11c898199a6f7d07b6/",
"sha": "6c1626a0d07e4bcfdbee4a11c898199a6f7d07b6"
}
],
"message": "document commit-in-porcelain-format endpoint in README"
}
},
"_links": {
"self": "http://localhost:5000/repos/restfulgit/branches/master/"
}
}Retrieves a list of other branches that have been merged into the given branch:
GET /repos/:repo_key/branches/:branch_name/merged/
[
{
"name": "ambiguous",
"commit": {
"sha": "1f51b91ac383806df9d322ae67bbad3364f50811",
"url": "http://localhost/repos/restfulgit/commits/1f51b91ac383806df9d322ae67bbad3364f50811/",
}
},
...
]Retrieves a list of commits that are unique to the branch (not in any other ref), sorted either chronologically or topologically:
GET /repos/example/branches/:branch_name/unique-commits/sorted/chronological/
GET /repos/example/branches/:branch_name/unique-commits/sorted/topological/
{
"commits": [
{
"sha": "c655dffe0fed2a78dc5f38c1bc8e5628e2605017",
"url": "http://localhost/repos/my-project/commits/c655dffe0fed2a78dc5f38c1bc8e5628e2605017/",
"commit": {
"sha": "c655dffe0fed2a78dc5f38c1bc8e5628e2605017",
"url": "http://localhost/repos/example/git/commits/c655dffe0fed2a78dc5f38c1bc8e5628e2605017/",
"author": {...},
"committer": {...},
"message": "",
"parents": [...],
"tree": {...}
},
"author": {...},
"committer": {...},
"parents": [...]
},
...
]
}Retrieves a specific blob object:
GET /repos/:repo_key/git/blobs/:sha/
{
"url": "http://localhost:5000/repos/restfulgit.git/git/blobs/0d20b6487c61e7d1bde93acf4a14b7a89083a16d/",
"sha": "0d20b6487c61e7d1bde93acf4a14b7a89083a16d",
"encoding": "utf-8",
"data": "*.pyc ",
"size": 6
}Retrieves a specific tree object:
GET /repos/:repo_key/git/trees/:sha/
optional: ?recursive=:zero_or_one (default=0, non-recursive)
{
"url": "http://localhost:5000/repos/restfulgit.git/git/trees/4c392547aa3d644877f3b22e198a5caac99a69a3/",
"sha": "4c392547aa3d644877f3b22e198a5caac99a69a3",
"tree": [
{
"url": "http://localhost:5000/repos/restfulgit.git/git/blobs/0d20b6487c61e7d1bde93acf4a14b7a89083a16d/",
"sha": "0d20b6487c61e7d1bde93acf4a14b7a89083a16d",
"mode": "0100644",
"path": ".gitignore",
"type": "blob",
"size": 6
},
...
]
}Retrieves a list of tags:
GET /repos/:repo_key/tags/
[
{
"name": "initial",
"url": "http://localhost:5000/repos/restfulgit/tags/initial/",
"commit": {
"url": "http://localhost:5000/repos/restfulgit/commits/07b9bf1540305153ceeb4519a50b588c35a35464/",
"sha": "07b9bf1540305153ceeb4519a50b588c35a35464"
}
},
...
]Retrieves a specific tag object by name:
GET /repos/:repo_key/tags/:tag_name/
{
"name": "initial",
"url": "http://localhost:5000/repos/restfulgit/tags/initial/",
"tag": {
"message": "initial commit\n",
"object": {
"sha": "07b9bf1540305153ceeb4519a50b588c35a35464",
"type": "commit",
"url": "http://localhost:5000/repos/restfulgit/git/commits/07b9bf1540305153ceeb4519a50b588c35a35464/"
},
"sha": "1dffc031c9beda43ff94c526cbc00a30d231c079",
"tag": "initial",
"tagger": {
"date": "2013-09-28T01:14:09Z",
"email": "[email protected]",
"name": "Chris Rebert"
},
"url": "http://localhost:5000/repos/restfulgit/git/tags/1dffc031c9beda43ff94c526cbc00a30d231c079/"
},
"commit": {
"author": {
"date": "2013-02-24T13:25:46Z",
"email": "[email protected]",
"name": "Rajiv Makhijani"
},
"commit": {
"author": {
"date": "2013-02-24T13:25:46Z",
"email": "[email protected]",
"name": "Rajiv Makhijani"
},
"committer": {
"date": "2013-02-24T13:25:46Z",
"email": "[email protected]",
"name": "Rajiv Makhijani"
},
"message": "Initial support for read-only REST api for Git plumbing",
"parents": [],
"sha": "07b9bf1540305153ceeb4519a50b588c35a35464",
"tree": {
"sha": "6ca22167185c31554aa6157306e68dfd612d6345",
"url": "http://localhost:5000/repos/restfulgit/git/trees/6ca22167185c31554aa6157306e68dfd612d6345/"
},
"url": "http://localhost:5000/repos/restfulgit/git/commits/07b9bf1540305153ceeb4519a50b588c35a35464/"
},
"committer": {
"date": "2013-02-24T13:25:46Z",
"email": "[email protected]",
"name": "Rajiv Makhijani"
},
"parents": [],
"sha": "07b9bf1540305153ceeb4519a50b588c35a35464",
"url": "http://localhost:5000/repos/restfulgit/commits/07b9bf1540305153ceeb4519a50b588c35a35464/"
}
}Retrieves a specific tag object by SHA:
GET /repos/:repo_key/git/tags/:tag_sha/
{
"url": "http://localhost:5000/repos/restfulgit.git/git/tags/89571737c474fae7ea4c092b5ed94e4eccb11b2a/",
"object": {
"url": "http://localhost:5000/repos/restfulgit.git/git/commits/b6b05bb0f230b591d82fcc07d169b7453e04cf89/",
"sha": "b6b05bb0f230b591d82fcc07d169b7453e04cf89",
"type": "commit"
},
"sha": "89571737c474fae7ea4c092b5ed94e4eccb11b2a",
"tag": "v0.1",
"tagger": {
"date": "2013-09-13T04:00:28Z",
"name": "Rajiv Makhijani",
"email": "[email protected]"
},
"message": "this is our first release"
}Retrieves a list of refs:
GET /repos/:repo_key/git/refs/
[
{
"url": "http://localhost:5000/repos/restfulgit.git/git/refs/heads/master",
"object": {
"url": "http://localhost:5000/repos/restfulgit.git/git/commits/f85df530d8413b0390364b291eb97d1cc5798dee/",
"sha": "f85df530d8413b0390364b291eb97d1cc5798dee",
"type": "commit"
},
"ref": "refs/heads/master"
}
...
]Retrieves a specific ref:
GET /repos/:repo_key/git/refs/:ref_name
Returns the raw file data for the file on the specified branch, tag, or commit SHA:
GET /repos/:repo_key/raw/:refspec/:file_path
Retrieves a list of general information about all of the repos:
GET /repos/
[
{
"name": "restfulgit",
"description": "REST API for Git data",
"url": "http://localhost:5000/repos/restfulgit/",
...
},
...
]Retrieve general information about a specific repo:
GET /repos/:repo_key/
{
"name": "restfulgit",
"full_name": "restfulgit",
"description": "REST API for Git data",
"url": "http://localhost:5000/repos/restfulgit/",
"commits_url": "http://localhost:5000/repos/restfulgit/commits{/sha}",
"blobs_url": "http://localhost:5000/repos/restfulgit/git/blobs{/sha}",
"branches_url": "http://localhost:5000/repos/restfulgit/branches{/branch}",
"tags_url": "http://localhost:5000/repos/restfulgit/tags/",
"trees_url": "http://localhost:5000/repos/restfulgit/git/trees{/sha}",
"git_commits_url": "http://localhost:5000/repos/restfulgit/git/commits{/sha}",
"git_refs_url": "http://localhost:5000/repos/restfulgit/git/refs{/sha}",
"git_tags_url": "http://localhost:5000/repos/restfulgit/git/tags{/sha}"
}Retrieve the diff between two commits each specified by branch name, tag name, or commit SHA:
GET /repos/:repo_key/compare/:refspec_1...:refspec_2.diff
optional: ?context=:num_context_lines (default=3; the number of lines to display before and after each hunk of the diff)
Content-Type: text/x-diff; charset=utf-8
diff --git a/README.md b/README.md
index 83e7371..c42b50e 100644
--- a/README.md
+++ b/README.md
@@ -183,6 +183,66 @@ Retrieves a list of branches:
]
...
Download a ZIP file or (gzipped) tarball of the contents of the repo at the specified branch, tag, or commit SHA:
GET /repos/:repo_key/zipball/:refspec/
GET /repos/:repo_key/tarball/:refspec/
Content-Type: application/zip
Content-Disposition: attachment; filename=restfulgit-master.zip
...
The zipball and gzipped-tarball features require that the Python standard library module zlib be available.
If zlib is unavailable, only the /tarball/ endpoint will be available, and it will send an uncompressed TAR file instead of a gzipped one.
Note that this endpoint may be slow as it does no caching.
Retrieves a list of contributors for the given repo, in descending order by number of commits in the main branch:
GET /repos/:repo_key/contributors/
[
...
{
"contributions": 23,
"email": "[email protected]",
"name": "Rajiv Makhijani"
},
...
]Contributors are presumed to be uniquely identifiable by their email address. Note that this endpoint may be slow as it involves walking through every single commit in the main branch and does no caching.
Retrieves blame information for lines in the given range of the given file at the specified branch, tag, or commit SHA:
GET /repos/:repo_key/blame/:refspec/:file_path
optional: ?firstLine=:line_num (default=1)
optional: ?lastLine=:line_num (default=number of lines in the file)
optional: ?oldest=:refspec (default=first commit in the repository; the oldest commit to consider; can be a branch, a tag, or a commit SHA)
{
"lines": [
{
"commit": "bcb720a10cd8452626e037673b3958facac9a789",
"line": "# coding=utf-8",
"origPath": "restfulgit/app.py",
"lineNum": 1
},
{
"commit": "bcb720a10cd8452626e037673b3958facac9a789",
"line": "from __future__ import absolute_import, unicode_literals, print_function, division",
"origPath": "restfulgit/app.py",
"lineNum": 2
},
...
],
"commits": {
"bcb720a10cd8452626e037673b3958facac9a789": {
"committer": {
"date": "2014-01-15T20:36:39Z",
"name": "Chris Rebert",
"email": "[email protected]"
},
"author": {
"date": "2014-01-04T01:10:41Z",
"name": "Chris Rebert",
"email": "[email protected]"
},
"url": "http://localhost:5000/repos/restfulgit/git/commits/bcb720a10cd8452626e037673b3958facac9a789/",
"tree": {
"url": "http://localhost:5000/repos/restfulgit/git/trees/8d50e406c9581433d2ec19d069fa32f3f03c43d8/",
"sha": "8d50e406c9581433d2ec19d069fa32f3f03c43d8"
},
"sha": "bcb720a10cd8452626e037673b3958facac9a789",
"parents": [
{
"url": "http://localhost:5000/repos/restfulgit/git/commits/29c9c6ef4a1f4f78aee60418e31a2a535d2bc923/",
"sha": "29c9c6ef4a1f4f78aee60418e31a2a535d2bc923"
}
],
"message": "refactoring: split things out into a bunch more packages+modules"
},
...
}
}Retrieves a listing of the contents of a given directory at the given branch, tag, or commit.
GET /repos/:repo_key/contents/:directory_path
optional: ?ref=:refspec (default=the default branch; can be a branch, a tag, or a commit SHA)
[
{
"name": ".gitignore",
"path": ".gitignore",
"type": "file",
"size": 55,
"sha": "3eac043ba3a315bce813d557102bb69ff9511d19",
"url": "http://localhost:5000/repos/restfulgit/contents/.gitignore?ref=master",
"git_url": "http://localhost:5000/repos/restfulgit/git/blobs/3eac043ba3a315bce813d557102bb69ff9511d19/",
"_links": {
"self": "http://localhost:5000/repos/restfulgit/contents/.gitignore?ref=master",
"git": "http://localhost:5000/repos/restfulgit/git/blobs/3eac043ba3a315bce813d557102bb69ff9511d19/"
}
},
...
{
"name": "restfulgit",
"path": "restfulgit",
"type": "dir",
"size": 0,
"sha": "48dd8b941913f02cd22a1fa8f18355a4f81c5d78",
"url": "http://localhost:5000/repos/restfulgit/contents/restfulgit?ref=master",
"git_url": "http://localhost:5000/repos/restfulgit/git/trees/48dd8b941913f02cd22a1fa8f18355a4f81c5d78/",
"_links": {
"self": "http://localhost:5000/repos/restfulgit/contents/restfulgit?ref=master",
"git":"http://localhost:5000/repos/restfulgit/git/trees/48dd8b941913f02cd22a1fa8f18355a4f81c5d78/"
}
},
...
]Retrieves the contents of and the metadata about the given file at the given branch, tag, or commit.
GET /repos/:repo_key/contents/:file_path
optional: ?ref=:refspec (default=master; can be a branch, a tag, or a commit SHA)
{
"name": "LICENSE.md",
"path": "LICENSE.md",
"type": "file",
"encoding": "utf-8",
"size": 1056,
"sha": "bb27aa0a502f73c19837b96d1bd514ba95e0d404",
"url": "http://localhost:5000/repos/restfulgit/contents/LICENSE.md?ref=master",
"git_url": "http://localhost:5000/repos/restfulgit/git/blobs/bb27aa0a502f73c19837b96d1bd514ba95e0d404/",
"content": "...",
"_links": {
"self": "http://localhost:5000/repos/restfulgit/contents/LICENSE.md?ref=master",
"git": "http://localhost:5000/repos/restfulgit/git/blobs/bb27aa0a502f73c19837b96d1bd514ba95e0d404/"
}
}