A "universal" / normalized API wrapper for git hosting services.
Ви не можете вибрати більше 25 тем Теми мають розпочинатися з літери або цифри, можуть містити дефіси (-) і не повинні перевищувати 35 символів.
James Fenn 24b3e6e186 update version numbers & publish script 4 місяці тому
example-android updated dependencies & broke everything! yay! 4 місяці тому
example-js add basic js disk cache with node-persist 8 місяці тому
example-jvm implement memory / disk cache - fix #4 9 місяці тому
example-kotlinbrowser implement memory / disk cache - fix #4 9 місяці тому
example-nodejs fix node-persist dependency errors 4 місяці тому
gitrest update version numbers & publish script 4 місяці тому
gradle/wrapper updated dependencies & broke everything! yay! 4 місяці тому
npm update version numbers & publish script 4 місяці тому
.gitignore add basic js disk cache with node-persist 8 місяці тому
LICENSE Initial commit 11 місяці тому
README.md update readme 8 місяці тому
build.gradle updated dependencies & broke everything! yay! 4 місяці тому
gradle.properties begin kotlin-multiplatform implementation 11 місяці тому
gradlew begin kotlin-multiplatform implementation 11 місяці тому
gradlew.bat begin kotlin-multiplatform implementation 11 місяці тому
settings.gradle update packages, add jvm example, use optional string serialization 10 місяці тому


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"]