API Support

Overview

This page describes how we implement methods in BigBone to make sure they support the existing Mastodon APIs in the best possible way.

Mastodon Server API

Two versions of the API exists, V1 and V2, whereas most of the endpoints are still running under V1. If breaking changes occur, they implement a new method in V2 (or higher). V1 will be extended if it is possible (e.g. by adding a new field). The only endpoints that yet exist in V2 are the ones for fetching instance information and working with filters.

BigBone Client Library

Requirements

• BigBone must support the current and the previous major release of Mastodon server. The current version of Mastodon is 4.0.2. Based on this, BigBone must support all releases between 3.0.0 and 4.0.2.
• BigBone must be able to handle modifications to the current V1/V2 APIs of Mastodon server. Modifications include:
  • Addition of new fields
  • Modification to existing fields
  • Removal of existing fields

General Implementation Notes

Response Entities

• BigBone returns the most recent version of response entity (e.g. Status, Account, ...) which is documented on the Mastodon website. In cases, where our method calls hit an older Mastodon server that does not support a specific attribute, we will set a sensible default value in the response entity we return to the caller.
• For every Mastodon API version (V1, V2, ...) we provide separate response entity objects (e.g. Instance, InstanceV1, Filter, FilterV1).

Method Signatures

• All methods are annotated using a @MastodonMinServerVersion runtime annotation. The goal of this annotation is to specify the minimum server version that is required in order to make this call successful. During library initialization, we fetch the server version from the instance. When the method is invoked, we compare versions and if requirements are not met, we will throw a BigBoneVersionException. The caller can then decide how to proceed further (e.g. call another method or fail).
• If an endpoint in V1 is newly implemented in V2, we will rename our existing method method to methodV1 and implement a new method called method which points to the new API version. Also, the existing response object Response will be renamed to ResponseV1. A new response object targeting the new API will be introduced, called Response. Furthermore, method methodV1 will be marked deprecated.

Error Handling

• We perform parameter checks on method invocation. If something is phishy, we throw an IllegalArgumentException.
• Based on the HTTP status code returned from the Mastodon API, we return the following execptions to the caller:
  • 401: BigBoneUnauthorizedException
  • 404: BigBoneNotFoundException
  • 422: BigBoneUnprocessableEntityException

Deprecating Old API Endpoints

• When a new endpoint is implemented (e.g. in V2), we will add a new method and release it as part of a minor release. At the same time, we will mark the old implementation as deprecated.
• The deprecated code will be removed as part of the next major release.

Examples

POST /api/v1/reports

Method Signature

@JvmOverloads
fileReport(account_id: String, status_ids: List<String> = null, comment: String, forward: Boolean = false, category: String = null, rule_ids: List<Int> = null): Report

Method Behaviour

• All Mastodon versions:
  • Check if "account_id" is set. If not, throw IllegalArgumentException
  • Check if length of comment is <= 1000 chars. If not, throw IllegalArgumentException
• Mastodon >= 3.0.0:
  • If "forward" is set, forward attribute as part of Mastodon API server request.
• Mastodon >= 3.5.0:
  • Make sure that "category" and "rule_ids" are set. If this is not the case, throw IllegalArgumentException.
  • If "category" and "rule_ids" are set, forward them as part of Mastodon API Server request.
• Mastodon >= 4.0.0:
  • Make sure that "rule_ids" is set ("category" is optional). If this is not the case, throw IllegalArgumentException.
  • throw error if rule_ids is not set, otherwise pass request to Mastodon API

GET /api/v1/accounts/:id

Method Signature

getAccount(id: String): Account

Method Behaviour

• All Mastodon versions:
  • Check if "id" is set. If not, throw IllegalArgumentException
• Mastodon >= 3.0.0 and Mastodon < 3.3.0:
  • Set "Account.suspended" to "true", if a HTTP status code 410 is returned, otherwise set to "false"

POST /api/v1/follow_requests/:account_id/authorize

Method Signature

authorizeFollowRequest(accountId: String): Relationship

Method Behaviour

• All Mastodon versions:
  • Check if "accountId" is set. If not, throw IllegalArgumentException

GET /api/v1/mutes

Method Signature

@JvmOverloads
getMutes(max_id: String = null, since_id: String = null, limit: String = null, mute_expires_at: String = null): Account

Method Behaviour

• Mastodon >= 3.0.0:
  • Check if "max_id", "since_id", and/or "limit" are set. If yes, forward them as part of the Mastodon API server request.
• Mastodon >= 3.3.0:
  • Check if "mute_expires_at" is set. If yes, forward it as part of the Mastodon API server request.