Web Client features

An overview of features of the WebClient object beyond making simple HTTP requests. Some of these features may not be exclusive to the Web Client.

• 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.
• 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.
• Logging: Logs information at several log levels. Logging function can be configured.
• 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.