A "universal" / normalized API wrapper for git hosting services.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
James Fenn 24b3e6e186 update version numbers & publish script 11 months ago
example-android updated dependencies & broke everything! yay! 1 year ago
example-js add basic js disk cache with node-persist 1 year ago
example-jvm implement memory / disk cache - fix #4 1 year ago
example-kotlinbrowser implement memory / disk cache - fix #4 1 year ago
example-nodejs fix node-persist dependency errors 11 months ago
gitrest update version numbers & publish script 11 months ago
gradle/wrapper updated dependencies & broke everything! yay! 1 year ago
npm update version numbers & publish script 11 months ago
.gitignore add basic js disk cache with node-persist 1 year ago
LICENSE Initial commit 1 year ago
README.md update readme 1 year ago
build.gradle updated dependencies & broke everything! yay! 1 year ago
gradle.properties begin kotlin-multiplatform implementation 1 year ago
gradlew begin kotlin-multiplatform implementation 1 year ago
gradlew.bat begin kotlin-multiplatform implementation 1 year ago
settings.gradle update packages, add jvm example, use optional string serialization 1 year ago


Git-REST API Wrapper NPM JitPack Discord

This is a cross-platform API wrapper for GitHub, GitLab, and Gitea, in an attempt to normalize their API endpoints and promote interoperability. It is being written in Kotlin Multiplatform with ktor, and aims to target the JVM, Android, JS, and native platforms - in other words, (almost) everything that ktor supports.



JavaScript projects can use the library through either the NPM package or by using a compiled bundle hosted on the UNPKG CDN.

NPM Module

npm install git-rest-wrapper

Bundled JS

<script type="text/javascript" src="https://unpkg.com/git-rest-wrapper/bundle/gitrest.js"></script>

Gradle / Java

The :gitrest module is published on JitPack, which you can add to your project by copying the following to your root build.gradle at the end of "repositories".

allprojects {
  repositories {
    maven { url 'https://jitpack.io' }

To add the dependency to a module, copy this line into your app's build.gradle file.

implementation "dev.horrific.code.james.git-rest-wrapper:gitrest-jvm:$gitrest_version"

The Android dependency can be imported similarly, using the root gitrest dependency instead of gitrest-jvm; gradle should identify & download the gitrest-android variant automatically.

implementation "dev.horrific.code.james.git-rest-wrapper:gitrest:$gitrest_version"

Note: fixing duplicate META-INF files

Kotlin Multiplatform has a weird issue with dependency management that I haven't quite worked out; (#5)[https://code.horrific.dev/james/git-rest-wrapper/issues/5] documents some of my encounters with it. Hopefully you won't encounter this problem at all, but if you do, it should be enough to just add the following to your Android modules:

android {
    packagingOptions {
        merge 'META-INF/*.kotlin_module'

For any similar errors, adding a line to either merge or exclude 'META-INF/<file>' should do the trick.



After installing the module through NPM, the API wrapper can be used as detailed in the code snippet below.

const gitrest = require('git-rest-wrapper');
const provider = new gitrest.Client();

provider.getUser("fennifith").then((user) => console.log(user.name));

The bundled JS file works the same as the NPM module - except the gitrest object will be available in the global scope.

const provider = new gitrest.Client();

provider.getUser("fennifith").then((user) => console.log(user.name));


In Kotlin, you'll need to import me.jfenn.gitrest.gitrest and instantiate it as follows (adding or removing providers as you see fit).

val client = gitrest {
    providers = arrayOf(GithubProvider, GitlabProvider, GiteaProvider)
    cache = MemoryCache()

You can optionally add API keys per-domain to any of these providers by using the tokens Map as follows:

GiteaProvider.apply {
    tokens["code.horrific.dev"] = "abcxyz"

Endpoints can then be accessed using Kotlin Coroutines...

GlobalScope.launch {
    val repo = client.getRepo("gitea@code.horrific.dev:james/git-rest-wrapper")

Example Projects


The project uses Gradle builds for... err... most things. ./gradlew :{module}:test and ./gradle :{module}:run are fairly universal.

The :gitrest:jsBrowserTest task seems to fail sporadically trying to parse... /etc/fonts/fonts.conf? Well, it spits out a lot of logs about it, then fails to actually run any of its tests, so it's not doing very much. It's excluded by default from most gradle tasks.


URI Scheme

The library relies on its own identifier format similar to the URI syntax used in SSH - each identifier should be structured as provider@hostname:id.

  • provider represents the implementation that should be used for the endpoint, e.g. gitlab or gitea. If omitted, the wrapper will query various endpoints in an attempt to determine the correct implementation before making the request.
  • hostname represents the host/domain of the server that should be queried. If omitted, the implementation is left to the provider - github:fennifith/Attribouter will default to github.com, for example.
  • id represents the resource identifier of the item being fetched, specific to the endpoint used.

The provider and hostname values are optional when they can be supplemented by the values in the DEFAULT_PROVIDERS array. This is also used to "correct" hostnames in cases where the API is served from a different domain than the one provided - for example, github@github.com:some/repo will resolve to github@api.github.com:some/repo. For compatibility reasons, github@anything.can.go.here.github.com:some/repo will exhibit the same behavior.


  • getUser(login): login is the username of the requested user.
  • getRepo(repo): repo is the repository "path", i.e. {user}/{repo} - james/git-rest-wrapper, for example.
  • getRepoContributors(repo): repo is the repository "path", same as getRepo
  • getLicense(key): key is a short license identifier - refer to SPDX for a complete list (dependent on the server's implementation)


Not all data is complete for every provider/context. For example, Gitea doesn't provide any license information in their Repository model - so that data will obviously be missing.

Each data model contains id, context, and provider values with respect to the corresponding portions of the URI.

  • User
    • id: The username.
    • name: The full name of the user (defaults to login if unspecified).
    • url: The webpage / user-facing link to the user's profile.
    • avatarUrl: A link to the user's avatar / profile picture.
    • websiteUrl: The user's website / blog / external profile link.
    • email: The user's public email address.
    • bio: The user bio.
  • Repo
    • id: The repository slug identifier, i.e. james/git-rest-wrapper
    • description: The repository/project description.
    • url: The webpage / user-facing repository link.
    • websiteUrl: The project website or homepage.
    • gitUrlHttp: HTTP url for git clone
    • gitUrlSsh: SSH uri for git clone
    • license: Repository License object - may be incomplete/missing, depending on implementation.
    • defaultBranch: The default branch of the repository.
    • getRawFileUrl(branchName, filePath): endpoint used to access a raw file in the repository
  • License
    • id: The license identifier/key, according to SPDX
    • name: A full user-facing license name (defaults to key if unspecified)
    • description: A short summary / description of the license.
    • body: The full license text.
    • infoUrl: A user-facing link to license info (ex: choosealicense.com/licenses/mpl-2.0)
    • permissions: An array of license "permissions", ex. ["commercial-use", "distribution", "modification"]
    • conditions: An array of license "conditions", ex. ["disclose-source", "same-license"]
    • limitations: An array of license "limitations", ex. ["liability", "warranty"]