Skip to content

API Support rephrasing suggestion

Jump to bottom
Andreas edited this page Oct 23, 2023 · 1 revision

Note: The following will come into effect with the first official release of the BigBone library. Snapshot versions made available before that release might differ.

Mastodon API Overview

Mastodon provides access to its data over a REST API that is described in detail here. This API is versioned, with most endpoints currently being available under version 1. V1 endpoints will be extended when possible (e.g. by adding a new field), meaning that both query parameters and the actual data in entities being returned can differ between individual Mastodon server versions.

If breaking changes occur, a new endpoint is provided under versions 2 or higher, with eventual deprecation of the former version. Data returned by a V2 endpoint might be provided as an entity different from the previous endpoint.

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

BigBone Client Library

Requirements

  • BigBone must support the current major version of Mastodon server up to its latest release, and latest releases of any previous major versions that had a minor version released within the past 12 months. Versions that are explicitly stated to be at their end of life are exempt from this.
  • For the whole range of supported versions, BigBone must be able to handle API modifications between versions. These include:
    • Addition of new fields
    • Modification to existing fields
    • Removal of existing fields
  • Compatibility with unsupported versions is explicitly not a requirement. However, BigBone must offer a way to disable versions checks to allow callers to use the library with older server versions at their own risk.

** BELOW UNCHANGED **

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.
Clone this wiki locally