Web Client features

An overview of features of the WebClient object beyond making simple HTTP requests.

• Automatic Retries: The client will automatically retry messages when the request fails, the response indicates being rate-limited (respecting the server's Retry-After header), or general server errors. The retry parameters are configurable.
• Proxy Support: Exposes an API to HttpsProxyAgent to create an alternative transport in order to proxy traffic via another HTTP server. This currently only supports HTTP tunnels.
• Request Queuing: Manages a queue of requests in order to conserve resources and to implement automatic retries. The concurrency parameters are configurable.
• Decorated Responses: Values that are returned as part of headers such as X-Oauth-Scopes and X-Accepted-Oauth-Scopes are added onto the JSON response as properties (as scopes and acceptedScopes).
• Request Serialization: Requests are usually sent with method POST and Content-Type: application/x-www-form-urlencoded. But some of the values in the body require JSON serialization into a string before serialization of the body into url-encoded data (e.g. attachments and unfurls). The client handles this serialization and allows the user to just use JSON.

• File Handling: One of the only times a request needs to set a different Content-Type is when uploading a file (not using the content shortcut), in which case it should be set to multipart/form-data. The client also helps handle Buffers and Streams for files (inherited from the request transport).

• Promise/Callback Hybrid: Allows users of this client to work with either Promises or callback functions for async control flow.
• Web API Methods: The client defines JavaScript methods for all of the Slack Web API methods. These methods all follow a convention for the signature.
• Logging: Logs information at several log levels. Logging function can be configured.
• Pluggable Transport: The default HTTP "transport" uses the popular request module. The client allows this to be replaced, which is mostly useful for testing.
• User Agent Instrumentation: The client reports information about itself via the User-Agent request header. The format is @slack:client/${package version} ${os}/${os version} node/${node version}
• Configurable API URL: The client has a slackAPIUrl configuration property which can be used to change the base URL of requests sent to the API.
• Lifecycle Events: TODO document the lifecycle events of a WebClient

API Design Notes

Individual methods (called facets) purposely separate the required arguments from the optional arguments because this design allows optional arguments to be introduced without API breaking changes. One might propose that all arguments be passed in an object the way the optional arguments are passed, but that design necessitates more syntax for the caller on simple calls which use the defaults.

NOTE: this is a WIP, feel free to contribute edits.