From 2ebebac855451618e3a6ac4fac76388ba346d990 Mon Sep 17 00:00:00 2001 From: James Fenn Date: Tue, 23 Jun 2020 15:32:23 -0400 Subject: [PATCH] update readme with more examples --- README.md | 87 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 57 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 92ef511..e01affd 100644 --- a/README.md +++ b/README.md @@ -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 ``` -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. -- GitLab