mastodon4j
mastodon4j is mastodon client for Java and Kotlin.
Official API Doc
https://github.com/tootsuite/documentation/blob/master/Using-the-API/API.md
Sample App
Android App
Get Started
Mastodon4j publish in jitpack. Add it in your root build.gradle at the end of repositories:
allprojects {
repositories {
...
maven {
url 'https://jitpack.io'
}
}
}
compile 'com.github.sys1yagi.mastodon4j:mastodon4j:$version' compile 'com.github.sys1yagi.mastodon4j:mastodon4j-rx:$version'Check latest version on Jitpack
Usage
Get Public Timeline
kotlin
val client: MastodonClient = MastodonClient.Builder("mstdn.jp", OkHttpClient.Builder(), Gson()).build()
val timelines = Timelines(client) val statuses: List<Status> = timelines.getPublic().execute()java
MastodonClient client = new MastodonClient.Builder("mstdn.jp", new OkHttpClient.Builder(), new Gson()).build();
Timelines timelines = new Timelines(client);
try {
List<Status> statuses = timelines.getPublic(new Range()).execute();
statuses.forEach(status->{
System.out.println("=============");
System.out.println(status.getAccount().getDisplayName());
System.out.println(status.getContent());
}
);
}
catch (Mastodon4jRequestException e) {
e.printStackTrace();
}
Register App
If you want to access the auth required API, you need create client credential and get access token. see more docs
kotlin
val client: MastodonClient = MastodonClient.Builde("mstdn.jp", OkHttpClient.Builder(), Gson()).build() val apps = Apps(client) val appRegistration = apps.createApp( clientName = "client name", redirectUris = "urn:ietf:wg:oauth:2.0:oob", scope = Scope(Scope.Name.ALL), website = "https://sample.com" ).execute() save(appRegistration) // appRegistration needs to be saved.AppRegistration has client id and client secret.
java
MastodonClient client = new MastodonClient.Builder("mstdn.jp", new OkHttpClient.Builder(), new Gson()).build();
Apps apps = new Apps(client);
try {
AppRegistration registration = apps.createApp(
"mastodon4j-sample-app",
"urn:ietf:wg:oauth:2.0:oob",
new Scope(Scope.Name.ALL),
"https://sample.com"
).execute();
System.out.println("instance=" + registration.getInstanceName());
System.out.println("client_id=" + registration.getClientId());
System.out.println("client_secret=" + registration.getClientSecret());
}
catch (Mastodon4jRequestException e) {
int statusCode = e.getResponse().code();
// error handling.
}
OAuth login and get Access Token
kotlin
val client: MastodonClient = MastodonClient.Builder("mstdn.jp", OkHttpClient.Builder(), Gson()).build() val clientId = appRegistration.clientId val apps = Apps(client) val url = apps.getOAuthUrl(clientId, Scope(Scope.Name.ALL)) // url like bellow // https://:instance_name/oauth/authorize?client_id=:client_id&redirect_uri=:redirect_uri&response_type=code&scope=read // open url and OAuth login and get auth code val authCode = //... val clientSecret = appRegistration.clientSecret val redirectUri = appRegistration.redirectUri val accessToken = apps.getAccessToken(
clientId,
clientSecret,
redirectUri,
authCode,
"authorization_code"
) // accessToken needs to be saved.Get Home Timeline
kotlin
// Need parameter of accessToken val client: MastodonClient = MastodonClient.Builder("mstdn.jp", OkHttpClient.Builder(), Gson())
.accessToken(accessToken)
.build() val statuses: List<Status> = timelines.getHome().execute()Get raw json
v0.0.7 or later
kotlin
val client = //... val publicMethod = Public(client) publicMethod.getLocalPublic()
.doOnJson {
jsonString ->
// You can get raw json for each element.
println(jsonString)
}
.execute() Streaming API
v1.0.0 or later
kotlin
val client: MastodonClient = MastodonClient.Builder("mstdn.jp", OkHttpClient.Builder(), Gson())
.accessToken(accessToken)
.useStreamingApi()
.build() val handler = object : Handler {
override fun onStatus(status: Status) {
println(status.content)
}
override fun onNotification(notification: Notification) {
/* no op */
}
override fun onDelete(id: Long) {
/* no op */
}
}
val streaming = Streaming(client) try {
val shutdownable = streaming.localPublic(handler)
Thread.sleep(10000L)
shutdownable.shutdown()
}
catch(e: Mastodon4jRequestException) {
e.printStackTrace()
}
java
MastodonClient client = new MastodonClient.Builder("mstdn.jp", new OkHttpClient.Builder(), new Gson())
.accessToken(accessToken)
.useStreamingApi()
.build();
Handler handler = new Handler() {
@Override
public void onStatus(@NotNull Status status) {
System.out.println(status.getContent());
}
@Override
public void onNotification(@NotNull Notification notification) {
/* no op */
}
@Override
public void onDelete(long id) {
/* no op */
}
}
; Streaming streaming = new Streaming(client);
try {
Shutdownable shutdownable = streaming.localPublic(handler);
Thread.sleep(10000L);
shutdownable.shutdown();
}
catch (Exception e) {
e.printStackTrace();
}
Versioning
Implementation Progress
Methods
- GET
/api/v1/accounts/:id - GET
/api/v1/accounts/verify_credentials - PATCH
/api/v1/accounts/update_credentials - GET
/api/v1/accounts/:id/followers - GET
/api/v1/accounts/:id/following - GET
/api/v1/accounts/:id/statuses - POST
/api/v1/accounts/:id/follow - POST
/api/v1/accounts/:id/unfollow - POST
/api/v1/accounts/:id/block - POST
/api/v1/accounts/:id/unblock - POST
/api/v1/accounts/:id/mute - POST
/api/v1/accounts/:id/unmute - GET
/api/v1/accounts/relationships - GET
/api/v1/accounts/search - POST
/api/v1/apps - GET
/api/v1/blocks - GET
/api/v1/favourites - GET
/api/v1/follow_requests - POST
/api/v1/follow_requests/:id/authorize - POST
/api/v1/follow_requests/:id/reject - POST
/api/v1/follows - GET
/api/v1/instance - POST
/api/v1/media - GET
/api/v1/mutes - GET
/api/v1/notifications - GET
/api/v1/notifications/:id - POST
/api/v1/notifications/clear - GET
/api/v1/reports - POST
/api/v1/reports - GET
/api/v1/search - GET
/api/v1/statuses/:id - GET
/api/v1/statuses/:id/context - GET
/api/v1/statuses/:id/card - GET
/api/v1/statuses/:id/reblogged_by - GET
/api/v1/statuses/:id/favourited_by - POST
/api/v1/statuses - DELETE
/api/v1/statuses/:id - POST
/api/v1/statuses/:id/reblog - POST
/api/v1/statuses/:id/unreblog - POST
/api/v1/statuses/:id/favourite - POST
/api/v1/statuses/:id/unfavourite - GET
/api/v1/timelines/home - GET
/api/v1/timelines/public - GET
/api/v1/timelines/tag/:hashtag
Streaming
v1.0.0 or later
-
GET /api/v1/streaming/user -
GET /api/v1/streaming/public -
GET /api/v1/streaming/public/local -
GET /api/v1/streaming/hashtag -
GET /api/v1/streaming/hashtag/local
Auth
- Generate Url for OAuth
/oauth/authorize - POST password authorize
/oauth/tokenv0.0.2 or later - POST
/oauth/token
Rx
v0.0.2 or later
- RxAccounts
- RxApps
- RxBlocks
- RxFavourites
- RxFollowRequests
- RxFollows
- RxInstances
- RxMedia
- RxMutes
- RxNotifications
- RxReports
- RxSearch
- RxStatuses
- RxTimelines
Rx Streaming
v1.0.0 or later
-
GET /api/v1/streaming/user -
GET /api/v1/streaming/public -
GET /api/v1/streaming/public/local -
GET /api/v1/streaming/hashtag -
GET /api/v1/streaming/hashtag/local
Contribution
Reporting Issues
Found a problem? Want a new feature? First of all see if your issue or idea has already been reported. If don't, just open a new clear and descriptive issues
License
MIT License Copyright (c) 2017 Toshihiro Yagi Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.