2020-01-01 22:37:59 +01:00
---
title: Routes
description: How HTTP methods map to controllers and actions.
menu:
docs:
weight: 40
parent: dev
---
2022-11-20 07:34:38 +01:00
{{< caption-link url = "https://github.com/mastodon/mastodon/blob/master/config/routes.rb" caption = "config/routes.rb" > }}
2020-01-01 22:37:59 +01:00
2020-01-12 14:11:56 +01:00
## Explanation of routes {#routes}
2020-01-01 22:37:59 +01:00
Mastodon uses Ruby on Rails, which defines its router configuration at config/routes.rb. You may view the [Ruby on Rails routing guide ](https://guides.rubyonrails.org/routing.html ) for more detailed information, but this page will explain the basics of how Mastodon handles routing.
2020-01-12 14:11:56 +01:00
### How routes are constructed {#router}
2020-01-01 22:37:59 +01:00
`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:
{{< code title = "config/routes.rb excerpt" > }}
```ruby
namespace :api do
namespace :v1 do
resources :statuses, only [:create, :show, :destroy] do
scope module: :statuses do
resource :favourite, only: :create
resource :unfavourite, to: 'favourites#destroy'
member do
get :context
end
end
end
end
end
```
{{< / 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` .
2022-12-14 22:55:30 +01:00
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.
2020-01-01 22:37:59 +01:00
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.
2020-01-12 14:11:56 +01:00
### Available methods {#methods}
2020-01-01 22:37:59 +01:00
#### :index
2022-12-14 22:55:30 +01:00
Maps to HTTP GET, for a list. Handled by the #index action in a controller.
2020-01-01 22:37:59 +01:00
#### :show
2022-12-14 22:55:30 +01:00
Maps to HTTP GET, for a single view. Handled by the #show action in a controller.
2020-01-01 22:37:59 +01:00
#### :create
2022-12-14 22:55:30 +01:00
Maps to HTTP POST. Handled by the #create action in a controller.
2020-01-01 22:37:59 +01:00
#### :update
2022-12-14 22:55:30 +01:00
Maps to HTTP PUT. Handled by the #update action in a controller.
2020-01-01 22:37:59 +01:00
#### :destroy
2022-12-14 22:55:30 +01:00
Maps to HTTP DELETE. Handled by the #destroy action in a controller.
2020-01-01 22:37:59 +01:00
2020-01-12 14:11:56 +01:00
## .well-known {#well-known}
2020-01-01 22:37:59 +01:00
2020-01-12 14:11:56 +01:00
### /.well-known/host-meta {#host-meta}
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Extensible Resource Descriptor (XRD). Advertises existence of Webfinger.
2020-01-01 22:37:59 +01:00
2020-01-12 14:11:56 +01:00
### /.well-known/nodeinfo {#nodeinfo}
2020-01-01 22:37:59 +01:00
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.
2022-12-14 22:55:30 +01:00
### /.well-known/webfinger {#webfinger}
2020-01-01 22:37:59 +01:00
2022-11-20 07:34:38 +01:00
Used for discovering ActivityPub actor id. See [Spec compliance > WebFinger ]({{< relref "spec/webfinger" >}} ) for more information.
2020-01-01 22:37:59 +01:00
2020-01-12 14:11:56 +01:00
### /.well-known/change-password {#change-password}
2020-01-01 22:37:59 +01:00
Maps to account settings page.
2020-01-12 14:11:56 +01:00
### /.well-known/keybase-proof-config {#keybase}
2020-01-01 22:37:59 +01:00
Used for integration with Keybase, defining which usernames are acceptable and where proofs may be checked.
{{< hint style = "warning" > }}
The sections below this point are under construction.
{{< / hint > }}
2020-01-12 14:11:56 +01:00
## Public URIs {#public}
2020-01-01 22:37:59 +01:00
* `/users/username` = user URI
* `/users/username/remote_follow` = remote follow dialog
* `/users/username/statuses/id` = status URI
2022-11-20 07:34:38 +01:00
* `/@username` = "posts" tab
* `/@username/with_replies` = "posts and replies" tab
2020-01-01 22:37:59 +01:00
* `/@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
2020-01-12 14:11:56 +01:00
## API {#api}
2020-01-01 22:37:59 +01:00
* /api/oembed
* /api/proofs
* /api/v1
2022-11-20 07:34:38 +01:00
* [statuses ]({{< relref "methods/statuses" >}} ) [create, show, destroy]
2022-12-14 22:55:30 +01:00
* reblogged_by [index]
* favourited_by [index]
2022-11-20 07:34:38 +01:00
* reblog [create]
2022-12-14 22:55:30 +01:00
* unreblog [POST reblog#destroy]
2022-11-20 07:34:38 +01:00
* favourite [create]
2022-12-14 22:55:30 +01:00
* unfavourite [POST favourites#destroy]
2022-11-20 07:34:38 +01:00
* bookmark [create]
2022-12-14 22:55:30 +01:00
* unbookmark [POST bookmarks#destroy]
2022-11-20 07:34:38 +01:00
* mute [create]
2022-12-14 22:55:30 +01:00
* unmute [POST mutes#destroy]
2022-11-20 07:34:38 +01:00
* pin [create]
2022-12-14 22:55:30 +01:00
* unpin [POST pins#destroy]
2022-11-20 07:34:38 +01:00
* context [GET]
* [timelines ]({{< relref "methods/timelines" >}} )
* home [show]
* public [show]
* tag [show]
* list [show]
* [streaming ]({{< relref "methods/streaming" >}} ) [index]
2022-12-14 22:55:30 +01:00
* [custom_emojis ]({{< relref "methods/custom_emojis" >}} ) [index]
2022-11-20 07:34:38 +01:00
* [suggestions ]({{< relref "methods/suggestions" >}} ) [index, destroy]
2022-12-14 22:55:30 +01:00
* [scheduled_statuses ]({{< relref "methods/scheduled_statuses" >}} ) [index, show, update, destroy]
2022-11-20 07:34:38 +01:00
* [preferences ]({{< relref "methods/preferences" >}} ) [index]
* [conversations ]({{< relref "methods/conversations" >}} ) [index, destroy]
* read [POST]
* [media ]({{< relref "methods/media" >}} ) [create, update]
* [blocks ]({{< relref "methods/blocks" >}} ) [index]
* [mutes ]({{< relref "methods/mutes" >}} ) [index]
* [favourites ]({{< relref "methods/favourites" >}} ) [index]
* [bookmarks ]({{< relref "methods/bookmarks" >}} ) [index]
* [reports ]({{< relref "methods/reports" >}} ) [create]
* [trends ]({{< relref "methods/trends" >}} ) [index]
* [filters ]({{< relref "methods/filters" >}} ) [index, create, show, update, destroy]
* [endorsements ]({{< relref "methods/endorsements" >}} ) [index]
* [markers ]({{< relref "methods/markers" >}} ) [index, create]
* [apps ]({{< relref "methods/apps" >}} ) [create]
2022-12-14 22:55:30 +01:00
* verify_credentials [credentials#show]
2022-11-20 07:34:38 +01:00
* [instance ]({{< relref "methods/instance" >}} ) [show]
* peers [index]
* activity [show]
2022-12-14 22:55:30 +01:00
* [domain_blocks ]({{< relref "methods/domain_blocks" >}} ) [show, create, destroy]
2022-11-20 07:34:38 +01:00
* [directory ]({{< relref "methods/directory" >}} ) [show]
2022-12-14 22:55:30 +01:00
* [follow_requests ]({{< relref "methods/follow_requests" >}} ) [index]
2022-11-20 07:34:38 +01:00
* authorize [POST]
* reject [POST]
* [notifications ]({{< relref "methods/notifications" >}} ) [index, show]
* clear [POST]
* dismiss [POST]
* [accounts ]({{< relref "methods/accounts" >}} )
2022-12-14 22:55:30 +01:00
* verify_credentials [GET credentials#show]
* update_credentials [PATCH credentials#update]
* search [show (search#index)]
2022-11-20 07:34:38 +01:00
* relationships [index]
* [accounts ]({{< relref "methods/accounts" >}} ) [create, show]
* statuses [index accounts/statuses]
2022-12-14 22:55:30 +01:00
* followers [index accounts/follower_accounts]
* following [index accounts/following_accounts]
2022-11-20 07:34:38 +01:00
* lists [index accounts/lists]
2022-12-14 22:55:30 +01:00
* identity_proofs [index accounts/identity_proofs]
2022-11-20 07:34:38 +01:00
* follow [POST]
* unfollow [POST]
* block [POST]
* unblock [POST]
* mute [POST]
* unmute [POST]
* pin [POST]
* unpin [POST]
* [lists ]({{< relref "methods/lists" >}} ) [index, create, show, update, destroy]
2022-12-14 22:55:30 +01:00
* accounts [POST accounts/pins#destroy]
* [featured_tags ]({{< relref "methods/featured_tags" >}} ) [index, create, destroy]
* suggestions [GET suggestions#index]
2022-11-20 07:34:38 +01:00
* [polls ]({{< relref "methods/polls" >}} ) [create, show]
* votes [create polls/votes]
* [push ]({{< relref "methods/push" >}} )
* subscription [create, show, update, destroy]
* [admin ]({{< relref "methods/admin" >}} )
* accounts [index, show]
* enable [POST]
* unsilence [POST]
* unsuspend [POST]
* approve [POST]
* reject [POST]
2022-12-14 22:55:30 +01:00
* action [create account_actions]
2022-11-20 07:34:38 +01:00
* reports [index, show]
2022-12-14 22:55:30 +01:00
* assign_to_self [POST]
2022-11-20 07:34:38 +01:00
* unassign [POST]
* reopen [POST]
* resolve [POST]
2020-01-01 22:37:59 +01:00
* /api/v2
2022-12-14 22:55:30 +01:00
* [search ]({{< relref "methods/search" >}} ) [GET search#index]
2020-01-01 22:37:59 +01:00