Routes
How HTTP methods map to controllers and actions.
Explanation of routes
Mastodon uses Ruby on Rails, which defines its router configuration at config/routes.rb. You may view the Ruby on Rails routing guide for more detailed information, but this page will explain the basics of how Mastodon handles routing.
How routes are constructed
namespace
is a prefix for routes mapped to a certain controller directory. resources
are mapped to controllers within that namespace directory. scope
passes to the module
’s controller. For example, consider the following abbreviated code:
The first available resource is :statuses, which is nested under the :api and :v1 namespaces. Thus, the resulting HTTP route will be /api/v1/statuses. The only
defines certain allowed methods, which are to be defined in the controller at app/controllers/api/v1/statuses_controller.rb
.
Within /api/v1/statuses, there is a scope for a module :statuses, where additional resources are defined. The controllers for these resources live in app/controllers/api/v1/statuses/
. For example, :favourite will be handled by the #create action within app/controllers/api/v1/statuses/favourites_controller.rb
and :unfavourite will be handled within the same controller, but by the #destroy action.
There is also a custom method defined for any member
within this scope, or in other words, for any status to be controlled by app/controllers/api/v1/statuses_controller.rb
, which is mapped to GET /api/v1/statuses/:id/context and handled by the :context action defined within that controller.
Available methods
:index
Maps to HTTP GET, for a list. Handled by the #index action in a controller.
:show
Maps to HTTP GET, for a single view. Handled by the #show action in a controller.
:create
Maps to HTTP POST. Handled by the #create action in a controller.
:update
Maps to HTTP PUT. Handled by the #update action in a controller.
:destroy
Maps to HTTP DELETE. Handled by the #destroy action in a controller.
.well-known
/.well-known/host-meta
Extensible Resource Descriptor (XRD). Advertises existence of Webfinger.
/.well-known/nodeinfo
Maps to NodeInfo 2.0 endpoint at /nodeinfo/2.0
, used for advertising software name and version, protocols, usage statistics, and whether registrations are open.
/.well-known/webfinger
Used for discovering ActivityPub actor id. See Spec compliance > WebFinger for more information.
/.well-known/change-password
Maps to account settings page.
/.well-known/keybase-proof-config
Used for integration with Keybase, defining which usernames are acceptable and where proofs may be checked.
Public URIs
/users/username
= user URI/users/username/remote_follow
= remote follow dialog/users/username/statuses/id
= status URI/@username
= “posts” tab/@username/with_replies
= “posts and replies” tab/@username/media
= “media” tab/@username/tagged/:hashtag
= tagged statuses by user/@username/:status_id
= status permalink/@username/:status_id/embed
= embeddable version/interact/:status_id
= remote interaction dialog/explore
= profile directory/explore/:hashtag
= profiles with this hashtag in bio/public
= public timeline preview/about
= landing page/about/more
= extended description/terms
= terms of service
API
- /api/oembed
- /api/proofs
- /api/v1
- statuses [create, show, destroy]
- reblogged_by [index]
- favourited_by [index]
- reblog [create]
- unreblog [POST reblog#destroy]
- favourite [create]
- unfavourite [POST favourites#destroy]
- bookmark [create]
- unbookmark [POST bookmarks#destroy]
- mute [create]
- unmute [POST mutes#destroy]
- pin [create]
- unpin [POST pins#destroy]
- context [GET]
- timelines
- home [show]
- public [show]
- tag [show]
- list [show]
- streaming [index]
- custom_emojis [index]
- suggestions [index, destroy]
- scheduled_statuses [index, show, update, destroy]
- preferences [index]
- conversations [index, destroy]
- read [POST]
- media [create, update]
- blocks [index]
- mutes [index]
- favourites [index]
- bookmarks [index]
- reports [create]
- trends [index]
- filters [index, create, show, update, destroy]
- endorsements [index]
- markers [index, create]
- apps [create]
- verify_credentials [credentials#show]
- instance [show]
- peers [index]
- activity [show]
- domain_blocks [show, create, destroy]
- directory [show]
- follow_requests [index]
- authorize [POST]
- reject [POST]
- notifications [index, show]
- clear [POST]
- dismiss [POST]
- accounts
- verify_credentials [GET credentials#show]
- update_credentials [PATCH credentials#update]
- search [show (search#index)]
- relationships [index]
- accounts [create, show]
- statuses [index accounts/statuses]
- followers [index accounts/follower_accounts]
- following [index accounts/following_accounts]
- lists [index accounts/lists]
- identity_proofs [index accounts/identity_proofs]
- follow [POST]
- unfollow [POST]
- block [POST]
- unblock [POST]
- mute [POST]
- unmute [POST]
- pin [POST]
- unpin [POST]
- lists [index, create, show, update, destroy]
- accounts [POST accounts/pins#destroy]
- featured_tags [index, create, destroy]
- suggestions [GET suggestions#index]
- polls [create, show]
- votes [create polls/votes]
- push
- subscription [create, show, update, destroy]
- admin
- accounts [index, show]
- enable [POST]
- unsilence [POST]
- unsuspend [POST]
- approve [POST]
- reject [POST]
- action [create account_actions]
- reports [index, show]
- assign_to_self [POST]
- unassign [POST]
- reopen [POST]
- resolve [POST]
- accounts [index, show]
- statuses [create, show, destroy]
- /api/v2
- search [GET search#index]
Last updated March 8, 2023 路 Improve this page