Browse Source

update readme with more examples

main
James Fenn 1 year ago
parent
commit
2ebebac855
1 changed files with 57 additions and 30 deletions
  1. +57
    -30
      README.md

+ 57
- 30
README.md View File

@@ -3,9 +3,7 @@ Git-REST API Wrapper [![NPM](https://img.shields.io/npm/v/git-rest-wrapper?color

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](https://kotlinlang.org/docs/reference/multiplatform.html) with [ktor](https://ktor.io/), and aims to target the JVM, Android, JS, and native platforms - in other words, (almost) everything that ktor supports.

## Usage

What are you doing here? This project isn't finished yet! I'll update this once more of the target platforms are complete.
## Installation

### JavaScript

@@ -17,29 +15,12 @@ JavaScript projects can use the library through either the [NPM package](https:/
npm install git-rest-wrapper
```

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

```js
const gitrest = require('git-rest-wrapper');
const provider = new gitrest.RequestProvider();

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

#### Bundled JS

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

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

```js
const provider = new gitrest.RequestProvider();

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

### Gradle / Java

The `:gitrest` module is published on [JitPack](https://jitpack.io/), which you can add to your project by copying the following to your root build.gradle at the end of "repositories".
@@ -59,15 +40,13 @@ To add the dependency to a module, copy this line into your app's build.gradle f
implementation "dev.horrific.code.james.git-rest-wrapper:gitrest-jvm:$gitrest_version"
```

### Android

The Android dependency can be imported similarly, using the `-android` dependency instead of `-jvm` (this isn't strictly necessary, but it does exclude a couple dependencies in place of Android APIs, reducing your overall APK size).

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

#### Fixing duplicate META-INF files
#### Note: fixing duplicate META-INF files

Kotlin Multiplatform has a weird issue with dependency management that I haven't quite worked out. Hopefully there'll be a better solution to this in the future, but for now it's enough to just add the following to your Android modules:

@@ -80,6 +59,54 @@ android {
}
```

## Usage

### JavaScript

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

```js
const gitrest = require('git-rest-wrapper');
const provider = new gitrest.RequestProvider();

provider.fetchUser("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.

```js
const provider = new gitrest.RequestProvider();

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

### Kotlin

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

```kotlin
const client = RequestProviderDelegate(arrayOf(
GithubProvider, GitlabProvider, GiteaProvider
))
```

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

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

Endpoints can then be accessed using [Kotlin Coroutines](https://kotlinlang.org/docs/reference/coroutines-overview.html)...

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

### Example Projects

- [Kotlin/JS - Browser](./example-kotlinbrowser)
@@ -88,15 +115,15 @@ android {
- [JVM](./example-jvm)
- [Android](./example-android)

### Development
## Development

The project uses Gradle builds for... err... most things.
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. I recommend appending `-x :gitrest:jsBrowserTest` to any gradle commands to prevent it from running.
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.

## Specification
### Specification

### URI Scheme
#### 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@context:id`.

@@ -104,14 +131,14 @@ The library relies on its own identifier format similar to the URI syntax used i
- `context` 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.

### Endpoints
#### Endpoints

- `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](https://spdx.org/licenses/) for a complete list (dependent on the server's implementation)

### Models
#### Models

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.



Loading…
Cancel
Save