Types to represent the Mastodon REST API.
Funcion to generate a request and parse the return.
Documentation starts at https://docs.joinmastodon.org/api/rest/accounts
{ server : String
, token : Maybe String
}
Used to create the HTTP URL and fill in its authentication token.
It's the host name for the URL.
Example server
: "mastodon.social".
A few requests do not require a token. Most do, and will error if you don't include one.
An API request.
Broken down as in the documentation.
Result entity types are documented with the various "xxxReq" types.
{ request : Request
, rawRequest : RawRequest
, metadata : Http.Metadata
, entity : Mastodon.Entity.Entity
}
A response from an API request.
The request
is a copy of the Request
that was sent over the wire,
for cases where that isn't obvious from the Entity
tag.
The metadata
is Http.Metadata
for a successful request, mostly so
you can get to the headers, if you need them.
Encodes an error from the server request.
Same as Http.Error
, but includes Http.Metadata
when it's available.
The String
in a BadStatus
is the Http error message, usually HTML.
The Error
in BadBody
is a Json.Decode.Error
. The String
in BadBody
is the JSON string returned by the Http request.
serverRequest : (id -> Result Error Response -> msg) -> List Http.Header -> ServerInfo -> id -> Request -> Platform.Cmd.Cmd msg
Create an HTTP request for the server.
The id
is whatever you need, besides the Request
, to identify the returned
Error
or Response
.
You will often pass []
for headers, but including a "User-Agent" header
is usually a good idea. For example, https://mammudeck.com uses:
[ Mastodon.Request.userAgentHeader "Mammudeck" ]
{ status : Maybe String
, in_reply_to_id : Maybe String
, group_id : Maybe String
, quote_of_id : Maybe String
, media_ids : List String
, poll : Maybe Mastodon.Entity.PollDefinition
, sensitive : Basics.Bool
, spoiler_text : Maybe String
, visibility : Maybe Mastodon.Entity.Visibility
, content_type : Maybe String
, scheduled_at : Maybe Mastodon.Entity.Datetime
, language : Maybe Mastodon.Entity.ISO6391
, idempotencyKey : Maybe String
}
Fields for a new Status
{ status : Maybe String
, in_reply_to_id : Maybe String
, quote_of_id : Maybe String
, media_ids : Maybe (List String)
, sensitive : Basics.Bool
, spoiler_text : Maybe String
, visibility : Maybe Mastodon.Entity.Visibility
, content_type : Maybe String
, poll : Maybe Mastodon.Entity.PollDefinition
, scheduled_at : Maybe Mastodon.Entity.Datetime
}
Fields for an edited Status
.
Parameter to Request.PutStatus
.
content_type
is "text/plain" or "text/markdown"
Sent over the wire to a Rebased server, from Soapbox:
{"status":"A status to edit with Mammudeck..."
,"in_reply_to_id":null
,"quote_id":null
,"media_ids":[]
,"sensitive":false
,"spoiler_text":""
,"visibility":"public"
,"content_type":"text/markdown"
,"poll":null
,"scheduled_at":null
,"to":[]
}
GET/POST /api/v1/statuses
GetStatus
, PostStatus
, PutStatus
, PostReblogStatus
, PostUnreblogStatus
, PostPinStatus
, and PostUnpinStatus
result in a StatusEntity
.
GetStatusSource
results in a StatusSourceEntity
GetStatusHistory
results in a HistoryStatusListEntity
GetStatusContext
results in a ContextEntity
.
GetStatusPartialContext
results in a StatusListEntity
. It is supported only by TruthSocial.com. The offset
parameter is for DescendantsContext
only. It is used to page through responses.
GetStatusCard
results in a CardEntity
.
GetStatusRebloggedBy
and GetStatusFavouritedBy
result in an AccountListEntity
.
DeleteStatus
results in NoEntity
.
The GetXxx
requests require no authentication token.
GET/POST /api/v1/timelines
GetHomeTimeline
, GetPublicTimeline
, GetProTimeline
, GetTagTimeline
, and GetListTimeline
result in a StatusListEntity
.
GetConversations
results in a ConversationListEntity
.
GetPublicTimeline
and GetTagTimeline
do not require an authentication token.
GET/POST/PATCH /api/v1/accounts
(and GET /api/v1/account_by_username
)
GetAccountByUsername
and GetAccount
do not require an authentication token.
GetAccountByUsername
, GetAccount
, GetVerifyCredentials
, and PatchUpdateCredentials
result in an AccountEntity
.
GetFollowers
, GetFollowing
, and GetSearchAccounts
result in an AccountListEntity
.
GetStatuses
results in a StatusListEntity
.
PostFollow
and PostUnfollow
result in a RelationshipEntity
.
GetRelationships
results in a RelationshipListEntity
.
GetAccountByUsername
(GET account_by_username
) is not documented, and may be Gab-only.
The fields_attributes
list in PatchUpdateCredentials
will be silently shortened to four elements if it's longer than that. If it's shorter than four elements, then the fields past those specified will be cleared.
GET/POST /api/v1/apps
PostApp
results in an AppEntity
.
These are not associated with your account on Mastodon servers, but
they need to be deleted when you're done with them on Pleroma servers
(if you use one to get a token, and you wouldn't bother to make it
except for that). I don't know yet how to delete them, except in the
Pleroma server's web API (the "Security" tab at
https://<pleroma-server.com>/user-settings
).
You will rarely use PostApp
directly, instead allowing the functions
in the Mastodon.Login
module to do that for you.
GET/POST /api/v1/blocks
GetBlocks
results in an AccountListEntity
.
PostBlock
and PostUnblock
result in a RelationshipEntity
.
GET /api/v8/custom_emojis
GetCustomEmojis
results in an EmojiListEntity
.
GET/POST /api/v8/domain_blocks
GetDomainBlocks
results in a StringListEntity
, a list of domain names.
PostDomainBlock
and DeleteDomainBlock
result in NoEntity
.
GET/POST /api/v1/endorsements
GetEndorsements
results in an AccountListEntity
.
PostPinAccount
and PostUnpinAccount
result in a RelationshipEntity
.
GET/POST /api/v1/favourites
GetFavourites
results in a StatusListEntity
.
PostFavourite
and PostUnfavorite
result in a StatusEntity
.
GET/POST/PUT /api/v1/filters
GetFilters
results in a FilterListEntity
.
PostFilter
, GetFilter
, and PutFilter
result in a FilterEntity
.
DeleteFilter
results in NoEntity
.
GET/POST /api/v1/follow_requests
GetFollowRequests
results in an AccountListEntity
.
PostAuthorizeFollow
and PostRejectFollow
result in NoEntity
.
GET/DELETE /api/v1/suggestions
GetFollowSuggestions
results in an AccountListEntity
.
DeleteFollowSuggestions
results in NoEntity
.
GET /api/v1/groups
The groups API is Gab-only.
GetGroups
results in a GroupListEntity
.
GetGroup
, PostGroup
, and PutGroup
result in a GroupEntity
GetGroupRelationships
results in a GroupRelationshipListEntity
.
GetGroupAccounts
and GetGroupRemovedAccounts
result in an AccountListEntity
.
PostGroupJoin
results in a GroupRelationshipEntity
.
DeleteGroupJoin
, DeleteGroupStatus
, PostGroupRemovedAccounts
, DeleteGroupRemovedAccounts
, and PatchGroupAddAdministrator
result in NoEntity
.
GetGroups
fetches the list of all groups of which the logged-in account is a member.
GetGroup
fetches one group.
GetGroupAccounts
returns the members of a group.
GetGroupRelationships
gets the logged-in account relationships for one or more groups.
PostGroup
creates a new group.
PutGroup
updates the group profile information.
PostGroupJoin
joins a group from the logged-in account.
DeletGroupJoin
leaves a group from the logged-in account.
DeleteGroupStatus
removes a status from the group.
GetGroupRemovedAccounts
returns the list of removed accounts for a group.
PostGroupRemovedAccounts
revokes group membership for an account.
DeleteGroupRemovedAccounts
removes a previously revoked membership from the list of deleted accounts.
PatchGroupAddAdministrator
adds an administrator to a group. There is currently no way to remove an administrator, except to remove the account from the group.
GET /api/v1/instance
GET/POST/PUT/DELETE /api/v1/lists
GetLists
and GetAccountLists
result in a ListEntityListEntity
.
GetListAccounts
results in an AccountListEntity
.
GetList
, PostList
, and PutList
result in a ListEntity
.
PostListAccounts
and DeleteListAccounts
result in NoEntity
.
GET/POST /api/v1/media
PostMedia
and PutMedia
result in an AttachmentEntity
.
GET/POST /api/v1/mutes
GetAccountMutes
results in an AccountListEntity
.
PostAccountMute
and PostAccountUnmute
result in a RelationshipEntity
.
PostStatusMute
and PostStatusUnmute
result in a StatusEntity
.
GET/POST /api/v1/notifications
GetNotifications
results in a NotificationListEntity
.
GetNotification
results in NotificationEntity
.
PostClearNotifications
and PostDismissNotifications
result in NoEntity
.
This doesn't yet define requests for "POST /api/v1/push/subscription", "GET /api/v1/push/subscription", "PUT /api/v1/push/subscription", or "DELETE /api/v1/push/subscription".
GET/POST /api/v1/polls
GetPoll
and PostVotes
result in a PollEntity
.
GetPoll
does not require an authentication token.
POST /api/v1/reports
PostReports
results in NoInstance
.
GET/PUT /api/v1/scheduled_statuses
GetScheduledStatuses
results in a ScheduledStatusListInstance
.
GetScheduledStatus
and PutScheduledStatus
result in a ScheduledStatusInstance
.
DeleteScheduledStatus
results in NoInstance
.
GET/POST /api/v1/search
GetSearch
results in a ResultsInstance
.
GET /api/v1/trends
GetTrends
results in a TagListEntity
.
{ max_id : Maybe String
, since_id : Maybe String
, min_id : Maybe String
, limit : Maybe Basics.Int
}
Parameters to control paging for requests that return lists.
{ privacy : Maybe Mastodon.Entity.Privacy
, sensitive : Maybe Basics.Bool
, language : Maybe (Maybe Mastodon.Entity.ISO6391)
}
Updated account Source
information
{ name : String
, value : Mastodon.Entity.HtmlString
}
Updated account Field
information.
Which groups to return from GetGroups { tab : WhichGroups }
Which context should GetStatusPartialContext return?
userAgentHeader : String -> Http.Header
Only required by GitHub that I know of, but can't hurt.
Pass whatever string describes your user agent. Or fake a common one.
idempotencyKeyHeader : String -> Http.Header
Create an "Idempotency-Key" header for use with PostStatus
.
Usually, you will create this header by passing Just key
for the
idempotencyKey
property of the parameter to PostStatus
, but if you
need to create it in another context, use this.
emptyPaging : Paging
The default Paging
instance, with no restrictions.
simplePostStatus : String -> Maybe String -> Maybe String -> Request
Create a PostStatus
request using only the most common non-blank fields.
Parameters are:
simplePostStatus status in_reply_to_id spoiler_text
{ method : String
, token : Maybe String
, url : String
, headers : List Http.Header
, body : Http.Body
, request : Request
, jsonBody : Maybe Json.Encode.Value
, decoder : Json.Decode.Decoder Mastodon.Entity.Entity
}
Represent an HTTP request.
Usually, you will let serverRequest
create one of these internally.
Sometimes, however, you need to create one yourself, or call
requestToRawRequest
to make one, make changes to it, and then call
rawRequestToCmd
.
requestToRawRequest : List Http.Header -> ServerInfo -> Request -> RawRequest
Convert a Request into a RawRequest.
You will usually not call this yourself, but let serverRequest
do it internally.
Sometimes, however, you need to call this to create a RawRequest
, modify it,
and then call rawRequestToCmd
to turn it into a Cmd
.
rawRequestToCmd : (Result Error Response -> msg) -> RawRequest -> Platform.Cmd.Cmd msg
Convert a RawRequest
into a Cmd
.
You will usually not call this yourself, but let serverRequest
do it internally.
Sometimes, however, you need to create a RawRequest
, by hand or by calling
requestToRawRequest
, then pass it here to turn it into a Cmd
.
rawRequestToTask : RawRequest -> Task Error Response
Same as rawRequestToCmd, but returns a Task
.
rawRequestToCmd
could be defined as:
rawRequestToCmd : (Result Error Response -> msg) -> RawRequest -> Cmd msg
rawRequestToCmd tagger rawRequest =
Task.attempt tagger <|
rawRequestToTask rawRequest
emptyRawRequest : RawRequest
An empty raw request.
Exposed only for testing in elm repl
.
emptyServerInfo : ServerInfo
For testing in elm repl
.