Nostrum.Api Module Decomposition

[kyleboe]

Some considerations and adjustments from the original spec in #536:

API Segmentation Changes

To explain some of the reasoning when extracting functions into modules, I let the following questions guide that decision-making:

Do the Discord docs call out the resource specifically?

For example, Nostrum.Api.AutoModeration is referenced here in the docs:

Otherwise, it would likely fall under the Guild module.

Can the module "stand alone"?

Or asked inversely; Do you only call the endpoint in the context of another resource?

For example, all Message endpoints begin with /channels/{channel.id}/messages in the URL.

This question is motivated by the goal of moving towards a consistent pattern around passing in the "root" struct as the first argument of the function:

%Nostrum.Struct.Message{id: 1234, channel_id: 5678}
|> Nostrum.Api.Message.react("\xF0\x9F\x98\x81")

Does the function name make it clear what is required and what is optional?

For example, calling Guild.ban_member implies that the Guild and the member (User) being banned are required.

This question has the most room for subjective interpretation because of the implicit nature of some related resources (i.e. you can't have a Message without a Channel or a Channel without a Guild)

---

Name Scheme Changes

With those questions in mind, a number of the endpoints had get_ and other implicit prefixes in the renamed functions and based on #536 (comment), I have gone ahead and made some of those changes:

• Nostrum.Api.ApplicationCommands
  • get_command_permissions => permissions
  • get_global_commands => global_commands
  • get_guild_command_permissions => guild_permissions
  • get_guild_commands => guild_commands
• Nostrum.Api.AutoModeration
  • create_auto_moderation_rule => create_rule
  • delete_auto_moderation_rule => delete_rule
  • get_auto_moderation_rule => rule
  • get_auto_moderation_rules => rules
  • modify_auto_moderation_rule => modify_rule
• Nostrum.Api.Guild
  • get_audit_log => audit_log
  • get_ban => ban
  • get_bans => bans
  • get_channels => channels
  • get_emoji => emoji
  • get_guild_integrations => integrations
  • get_member => member
  • get_roles => roles
  • get_scheduled_events => scheduled_events
  • get_webhooks => webhooks
  • get_widget => widget
  • get_voice_region => voice_region
  • list_guild_emojis => emojis
  • get_members => members
  • list_voice_regions => voice_regions
  • modify_integrations => modify_integration
• Nostrum.Api.ScheduledEvent
  - get_users => users
• Nostrum.Api.Self
  • get_application_information => application_information
  • get_dms => dms
• Nostrum.Api.Thread
  • get_member => member
  • get_members => members
  • list_threads => list
  • list_joined_private_archived_threads => joined_private_archived_threads
  • list_private_archived_threads => private_archived_threads
  • list_public_archived_threads => public_archived_threads
• Nostrum.Api.User
  • get_current_user_guilds => Nostrum.Api.Self.guilds
  • get_user_connections => Nostrum.Api.Self.connections
• Nostrum.Api.Interactions
  • get_original_response => original_response
• Nostrum.Api.Sticker (added)
  • create_guild_sticker => create
  • delete_guild_sticker => delete
  • get_guild_sticker => get
  • get_sticker_pack => pack
  • get_sticker_packs => packs
  • get_sticker => get
  • list_guild_stickers => list
  • modify_guild_sticker => modify

---

API Punchlist

Nostrum.Api

• request => request
• request_multipart => request_multipart

Nostrum.Api.ApplicationCommands

• batch_edit_application_command_permissions => batch_edit_permissions
• bulk_overwrite_global_application_commands => bulk_overwrite_global_commands
• bulk_overwrite_guild_application_commands => bulk_overwrite_guild_commands
• create_global_application_command => create_global_command
• create_guild_application_command => create_guild_command
• delete_global_application_command => delete_global_command
• delete_guild_application_command => delete_guild_command
• edit_application_command_permissions => edit_command_permissions
• edit_global_application_command => edit_global_command
• edit_guild_application_command => edit_guild_command
• get_application_command_permissions => permissions
• get_global_application_commands => global_commands
• get_guild_application_command_permissions => guild_permissions
• get_guild_application_commands => guild_commands

Nostrum.Api.AutoModeration

• create_guild_auto_moderation_rule => create_rule
• delete_guild_auto_moderation_rule => delete_rule
• get_guild_auto_moderation_rule => rule
• get_guild_auto_moderation_rules => rules
• modify_guild_auto_moderation_rule => modify_rule

Nostrum.Api.Channel

• add_pinned_channel_message => pin_message
• bulk_delete_messages => bulk_delete_messages
• create_guild_channel => create
• delete_channel => delete
• delete_channel_permissions => delete_permissions
• delete_pinned_channel_message => unpin_message
• edit_channel_permissions => edit_permissions
• get_channel => get
• get_channel_messages => messages
• get_channel_webhooks => webhooks
• get_pinned_messages => pinned_messages
• modify_channel => modify
• start_typing => start_typing

Nostrum.Api.Guild

• add_guild_member => add_member
• begin_guild_prune => begin_prune
• create_guild_ban => ban_member
• create_guild_emoji => create_emoji
• create_guild_integrations => create_integration
• delete_guild => delete
• delete_guild_emoji => delete_emoji
• delete_guild_integrations => delete_integration
• get_guild => get
• get_guild_audit_log => audit_log
• get_guild_ban => ban
• get_guild_bans => bans
• get_guild_channels => channels
• get_guild_emoji => emoji
• get_guild_integrations => integrations
• get_guild_member => member
• get_guild_prune_count => estimate_prune_count
• get_guild_roles => roles
• get_guild_scheduled_events => scheduled_events
• get_guild_webhooks => webhooks
• get_guild_widget => widget
• get_voice_region => voice_region
• leave_guild => leave
• list_guild_emojis => emojis
• list_guild_members => members
• list_voice_regions => voice_regions
• modify_current_user_nick => modify_self_nick
• modify_guild => modify
• modify_guild_channel_positions => modify_channel_positions
• modify_guild_emoji => modify_emoji
• modify_guild_integrations => modify_integration
• modify_guild_member => modify_member
• modify_guild_role_positions => modify_role_positions
• modify_guild_widget => modify_widget
• remove_guild_ban => unban_member
• remove_guild_member => kick_member
• sync_guild_integrations => sync_integrations
• add_guild_member_role => add_role_member
• create_guild_role => create_role
• delete_guild_role => delete_role
• modify_guild_role => modify_role
• remove_guild_member_role => remove_role_member

Nostrum.Api.Interactions

• create_followup_message => create_followup_message
• create_interaction_response => create_response
• delete_interaction_followup_message => delete_followup_message
• delete_interaction_response => delete_response
• edit_interaction_response => edit_response
• get_original_interaction_response => original_response

Nostrum.Api.Invites

• get_invite => get
• delete_invite => delete
• get_guild_invites => guild_invites
• create_channel_invite => create
• get_channel_invites => channel_invites

Nostrum.Api.Message

• create_message => create
• create_reaction => react
• delete_all_reactions => clear_reactions
• delete_message => delete
• delete_own_reaction => unreact
• delete_reaction => delete_emoji_reactions
• delete_user_reaction => delete_user_reaction
• edit_message => edit
• get_channel_message => get
• get_reactions => reactions

Nostrum.Api.Polls

• expire_poll => expire
• get_poll_answer_voters => answer_voters

Nostrum.Api.ScheduledEvent

• create_guild_scheduled_event => create
• delete_guild_scheduled_event => delete
• get_guild_scheduled_event => get
• get_guild_scheduled_event_users => users
• modify_guild_scheduled_event => modify

Nostrum.Api.Self

• get_application_information => application_information
• get_current_user => get
• get_token => token (I'm not sure where this function is/was but it isn't there now)
• get_user_dms => dms
• modify_current_user => modify
• update_shard_status => update_shard_status
• update_status => update_status
• update_voice_status => update_voice_status

Nostrum.Api.Sticker

• create_guild_sticker => create
• delete_guild_sticker => delete
• get_guild_sticker => get
• get_sticker_pack => pack
• get_sticker_packs => packs
• get_sticker => get
• list_guild_stickers => list
• modify_guild_sticker => modify

Nostrum.Api.Thread

• add_thread_member => add_member
• get_thread_member => member
• get_thread_members => members
• join_thread => join
• leave_thread => leave
• list_guild_threads => list
• list_joined_private_archived_threads => joined_private_archived_threads
• list_private_archived_threads => private_archived_threads
• list_public_archived_threads => public_archived_threads
• remove_thread_member => remove_member
• start_thread => create
• start_thread_in_forum_channel => create_in_forum
• start_thread_with_message => create_with_message

Nostrum.Api.User

• create_dm => create_dm
• create_group_dm => create_group_dm
• get_current_user_guilds => Nostrum.Api.Self.guilds
• get_user => get
• get_user_connections => Nostrum.Api.Self.connections

Nostrum.Api.Webhook

• create_webhook => create
• delete_webhook => delete
• edit_webhook_message => edit_message
• execute_git_webhook => execute_git
• execute_slack_webhook => execute_slack
• execute_webhook => execute
• get_webhook => get
• get_webhook_message => get_message
• get_webhook_with_token => get_with_token
• modify_webhook => modify
• modify_webhook_with_token => modify_with_token

[kyleboe]

I think all of the updates are made. I've walked through a self-review a couple times now and I think I've updated most everything (including the docs to represent the moved/changed modules).

[kyleboe]

Looks like I still need one more review before I can merge this. Any takers? @Kraigie

[broman]

LGTM

[Kraigie]

Looks like I still need one more review before I can merge this. Any takers? @Kraigie

@kyleboe I reached out to Joe and the Volcster. Just wanted to check in first to see how they feel about it as they've done way more maintaining as of late. This does LGTM though!