https://github.com/mattbdean/jraw
The Java Reddit API Wrapper
https://github.com/mattbdean/jraw
api gradle java oauth reddit reddit-api
Last synced: 6 months ago
JSON representation
The Java Reddit API Wrapper
- Host: GitHub
- URL: https://github.com/mattbdean/jraw
- Owner: mattbdean
- License: mit
- Created: 2014-05-14T01:51:42.000Z (over 11 years ago)
- Default Branch: master
- Last Pushed: 2021-11-21T19:28:15.000Z (almost 4 years ago)
- Last Synced: 2025-04-05T10:08:33.133Z (6 months ago)
- Topics: api, gradle, java, oauth, reddit, reddit-api
- Language: Kotlin
- Homepage: https://mattbdean.gitbooks.io/jraw
- Size: 6.59 MB
- Stars: 357
- Watchers: 30
- Forks: 128
- Open Issues: 37
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/mattbdean/JRAW)
[](https://bintray.com/thatjavanerd/maven/JRAW/_latestVersion)
[](http://kotlinlang.org)
[](https://github.com/thatJavaNerd/JRAW/blob/master/ENDPOINTS.md)
[](https://codecov.io/gh/mattbdean/JRAW)
```groovy
repositories {
jcenter()
}
dependencies {
implementation "net.dean.jraw:JRAW:$jrawVersion"
}
```
## Documentation
The full documentation is available [on GitBooks](https://mattbdean.gitbooks.io/jraw), but here's a sneak peek:
```java
// Assuming we have a 'script' reddit app
Credentials oauthCreds = Credentials.script(username, password, clientId, clientSecret);
// Create a unique User-Agent for our bot
UserAgent userAgent = new UserAgent("bot", "my.cool.bot", "1.0.0", "myRedditUsername");
// Authenticate our client
RedditClient reddit = OAuthHelper.automatic(new OkHttpNetworkAdapter(userAgent), oauthCreds);
// Get info about the user
Account me = reddit.me().about();
```
### Javadoc
JRAW uses JitPack to host its Javadoc.
```
https://jitpack.io/com/github/mattbdean/JRAW/VERSION/javadoc/index.html
```
`VERSION` can be a specific commit hash (like [`d6843bf`](https://jitpack.io/com/github/mattbdean/JRAW/d6843bf/javadoc/index.html)), a tag (like [`v1.0.0`](https://jitpack.io/com/github/mattbdean/JRAW/v1.0.0/javadoc/index.html)), or the HEAD of a branch (like [`master-SNAPSHOT`](https://jitpack.io/com/github/mattbdean/JRAW/master-SNAPSHOT/javadoc/index.html)).
JitPack produces Javadoc only when necessary, so the first time someone accesses the Javadoc for a specific build it may take a little bit.
## Android
JRAW doesn't target Android specifically, but there is an [extension library](https://github.com/mattbdean/JRAW-Android) that solves some quality of life issues. Also be sure to check out the [example app](https://github.com/mattbdean/JRAW-Android/tree/master/example-app) that shows how to get users logged in.
## Contributing
To get started you'll need to create two [reddit OAuth2 apps](https://www.reddit.com/prefs/apps), one script and one installed, and then create a subreddit.
To have this done automatically for you, run this command:
```sh
$ ./gradlew :meta:credentials --no-daemon --console plain
```
Your testing account should have at least 100 karma, otherwise you'll run into issues when trying to create a subreddit.
`lib/src/test/resources/credentials.json`:
```json
{
"script": {
"username": "...",
"password": "...",
"clientId": "...",
"clientSecret": "..."
},
"app": {
"clientId": "...",
"redirectUrl": "..."
},
"moderationSubreddit": "..."
}
```
Then you can go ahead and run the tests
```sh
$ ./gradlew test
```
Tests are written with [Spek](http://spekframework.org/) and assertions are done with [Expekt](https://github.com/winterbe/expekt).
In order to get the integration tests of the `docs` module to pass, you'll need [gitbook-cli](https://github.com/GitbookIO/gitbook-cli) installed globally. You shouldn't have to worry about this, as most of the contributions are likely to be towards the core library and not its accessory modules.
### Code Style
Kotlin code follows the [official conventions](https://kotlinlang.org/docs/reference/coding-conventions.html) provided by JetBrains (with a few exceptions).
A few hard and fast rules:
- UTF-8 everywhere
- 4 spaces for indentation
- 120 line length
## Releasing
Define these variables in `gradle.properties`:
```properties
# Go to gitbook.com -> Account Settings -> Applications/Tokens to get an API key
gitbookUsername=
gitbookPassword=
# Go to bintray.com -> Edit Profile -> API Key to get your account's API key
bintrayUser=
bintrayKey=
# If this property doesn't match the target release, all release-related tasks
# will be disabled
authorizeRelease=
```
Update the version in the root [build.gradle](https://github.com/mattbdean/JRAW/blob/master/build.gradle) and then run the `:lib:release` task to perform a release.
```
$ ./gradlew release --no-daemon --console plain
```
This task will:
1. Clean everything and run `:lib`'s tests
2. Run `:meta:update` (see [here](https://github.com/mattbdean/JRAW/tree/master/meta) for what this does)
3. Creates a commit for the version. This commit must be pushed manually later.
4. Updates the GitBook site and creates a new tag in the Git repo.
5. Uploads artifacts (sources, Javadoc, and compiled) to [Bintray](https://bintray.com/thatjavanerd/maven/JRAW)
After running the task:
1. Push the newly-created commit
2. Create a [GitHub release](https://github.com/mattbdean/JRAW/releases/new) targeting that commit. Attach all jars generated in `lib/build/libs`.
3. Publish the uploaded jars on [Bintray](https://bintray.com/thatjavanerd/maven/JRAW)