RestfulGit: A Restful API for Git data

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 3
Flask
pygit2 (This project works ok with the latest version 1.0.1 as of Jan 2020), which itself requires the C library libgit2. Before installing the Python pygit2 package first install the libgit2 dependency:
- On Mac brew install libgit2
- On Linux sudo apt install libgit2-dev

Optional:

filemagic (= 1.6) (offers improved MIME-type guessing), which itself requires libmagic (= 5.11)
Note: filemagic usage not yet tested with this Python 3 port, though filemagic is still the same version 1.6 as of Jan 2020

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.)

Example installation, config and run:

Assuming Mac.

brew install libgit2
cp example_config.py config.py

Edit config.py e.g. set the root directory to look for git repositories RESTFULGIT_REPO_BASE_PATH = '/tmp/myrepos/'

Create a virtual environment and install dependencies - assuming Pipenv:

pipenv --python 3
pipenv install
pipenv shell

otherwise set up a virtual enviroment using your favourite technique (if you choose to use a virtual environment) then run the usual pip -r requirements.txt

Running the server on a development machine:

export RESTFULGIT_CONFIG=/.../config.py
python -m restfulgit.app

The RESTFULGIT_CONFIG environment variable should point to the config.py you just edited.

The -m parameter restfulgit.app refers to the module path and thus to the file restfulgit/app.py where you can see this project's bootstrapping code for Flask.

Configuration

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. Restfulgit will look for 5 repositories deep in directory tree. | | 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.

For repositories within directories slashes should be replaced with ; (semicolon). If there is ; in directory name, it can be encoded with ;;.

Commits

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": "rajiv@hulu.com"
        },
        "committer": {
            "date": "2013-05-20T23:11:30Z",
            "name": "Rajiv Makhijani",
            "email": "rajiv@hulu.com"
        },
        "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": "rajiv@hulu.com"
    },
    "committer": {
        "date": "2013-02-24T13:25:46Z",
        "name": "Rajiv Makhijani",
        "email": "rajiv@hulu.com"
    },
    "parents": [],
    "commit": {
        "committer": {
            "date": "2013-02-24T13:25:46Z",
            "name": "Rajiv Makhijani",
            "email": "rajiv@hulu.com"
        },
        "author": {
            "date": "2013-02-24T13:25:46Z",
            "name": "Rajiv Makhijani",
            "email": "rajiv@hulu.com"
        },
        "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": "rajiv@hulu.com"
    },
    "author": {
        "date": "2013-02-24T13:25:46Z",
        "name": "Rajiv Makhijani",
        "email": "rajiv@hulu.com"
    },
    "url": "http://localhost:5000/repos/restfulgit/git/commits/07b9bf1540305153ceeb4519a50b588c35a35464/",
    "tree": {
        "url": "http://localhost:5000/repos/restfulgit/git/trees/6ca22167185c31554aa6157306e6

Restfulgit

Install / Use

README

RestfulGit: A Restful API for Git data

Example installation, config and run:

Configuration

Commits

Related Skills