move each API doc into its own file

docs/api/web-request.md

@@ -0,0 +1,205 @@
+## Class: WebRequest
+
+> Intercept and modify the contents of a request at various stages of its lifetime.
+
+Process: [Main](../tutorial/quick-start.md#main-process)
+
+Instances of the `WebRequest` class are accessed by using the `webRequest`
+property of a `Session`.
+
+The methods of `WebRequest` accept an optional `filter` and a `listener`. The
+`listener` will be called with `listener(details)` when the API's event has
+happened. The `details` object describes the request. Passing `null`
+as `listener` will unsubscribe from the event.
+
+The `filter` object has a `urls` property which is an Array of URL
+patterns that will be used to filter out the requests that do not match the URL
+patterns. If the `filter` is omitted then all requests will be matched.
+
+For certain events the `listener` is passed with a `callback`, which should be
+called with a `response` object when `listener` has done its work.
+
+An example of adding `User-Agent` header for requests:
+
+```javascript
+const {session} = require('electron')
+
+// Modify the user agent for all requests to the following urls.
+const filter = {
+  urls: ['https://*.github.com/*', '*://electron.github.io']
+}
+
+session.defaultSession.webRequest.onBeforeSendHeaders(filter, (details, callback) => {
+  details.requestHeaders['User-Agent'] = 'MyAgent'
+  callback({cancel: false, requestHeaders: details.requestHeaders})
+})
+```
+
+### Instance Methods
+
+The following methods are available on instances of `WebRequest`:
+
+#### `webRequest.onBeforeRequest([filter, ]listener)`
+
+* `filter` Object
+* `listener` Function
+  * `details` Object
+    * `id` Integer
+    * `url` String
+    * `method` String
+    * `resourceType` String
+    * `timestamp` Double
+    * `uploadData` [UploadData[]](structures/upload-data.md)
+  * `callback` Function
+    * `response` Object
+      * `cancel` Boolean (optional)
+      * `redirectURL` String (optional) - The original request is prevented from
+        being sent or completed and is instead redirected to the given URL.
+
+The `listener` will be called with `listener(details, callback)` when a request
+is about to occur.
+
+The `uploadData` is an array of `UploadData` objects.
+
+The `callback` has to be called with an `response` object.
+
+#### `webRequest.onBeforeSendHeaders([filter, ]listener)`
+
+* `filter` Object
+* `listener` Function
+
+The `listener` will be called with `listener(details, callback)` before sending
+an HTTP request, once the request headers are available. This may occur after a
+TCP connection is made to the server, but before any http data is sent.
+
+* `details` Object
+  * `id` Integer
+  * `url` String
+  * `method` String
+  * `resourceType` String
+  * `timestamp` Double
+  * `requestHeaders` Object
+* `callback` Function
+  * `response` Object
+    * `cancel` Boolean (optional)
+    * `requestHeaders` Object (optional) - When provided, request will be made
+      with these headers.
+
+The `callback` has to be called with an `response` object.
+
+#### `webRequest.onSendHeaders([filter, ]listener)`
+
+* `filter` Object
+* `listener` Function
+  * `details` Object
+    * `id` Integer
+    * `url` String
+    * `method` String
+    * `resourceType` String
+    * `timestamp` Double
+    * `requestHeaders` Object
+
+The `listener` will be called with `listener(details)` just before a request is
+going to be sent to the server, modifications of previous `onBeforeSendHeaders`
+response are visible by the time this listener is fired.
+
+#### `webRequest.onHeadersReceived([filter, ]listener)`
+
+* `filter` Object
+* `listener` Function
+
+The `listener` will be called with `listener(details, callback)` when HTTP
+response headers of a request have been received.
+
+* `details` Object
+  * `id` String
+  * `url` String
+  * `method` String
+  * `resourceType` String
+  * `timestamp` Double
+  * `statusLine` String
+  * `statusCode` Integer
+  * `responseHeaders` Object
+* `callback` Function
+  * `response` Object
+    * `cancel` Boolean
+    * `responseHeaders` Object (optional) - When provided, the server is assumed
+      to have responded with these headers.
+    * `statusLine` String (optional) - Should be provided when overriding
+      `responseHeaders` to change header status otherwise original response
+      header's status will be used.
+
+The `callback` has to be called with an `response` object.
+
+#### `webRequest.onResponseStarted([filter, ]listener)`
+
+* `filter` Object
+* `listener` Function
+  * `details` Object
+    * `id` Integer
+    * `url` String
+    * `method` String
+    * `resourceType` String
+    * `timestamp` Double
+    * `responseHeaders` Object
+    * `fromCache` Boolean - Indicates whether the response was fetched from disk
+      cache.
+    * `statusCode` Integer
+    * `statusLine` String
+
+The `listener` will be called with `listener(details)` when first byte of the
+response body is received. For HTTP requests, this means that the status line
+and response headers are available.
+
+#### `webRequest.onBeforeRedirect([filter, ]listener)`
+
+* `filter` Object
+* `listener` Function
+  * `details` Object
+    * `id` String
+    * `url` String
+    * `method` String
+    * `resourceType` String
+    * `timestamp` Double
+    * `redirectURL` String
+    * `statusCode` Integer
+    * `ip` String (optional) - The server IP address that the request was
+      actually sent to.
+    * `fromCache` Boolean
+    * `responseHeaders` Object
+
+The `listener` will be called with `listener(details)` when a server initiated
+redirect is about to occur.
+
+#### `webRequest.onCompleted([filter, ]listener)`
+
+* `filter` Object
+* `listener` Function
+  * `details` Object
+    * `id` Integer
+    * `url` String
+    * `method` String
+    * `resourceType` String
+    * `timestamp` Double
+    * `responseHeaders` Object
+    * `fromCache` Boolean
+    * `statusCode` Integer
+    * `statusLine` String
+
+The `listener` will be called with `listener(details)` when a request is
+completed.
+
+#### `webRequest.onErrorOccurred([filter, ]listener)`
+
+* `filter` Object
+* `listener` Function
+  * `details` Object
+    * `id` Integer
+    * `url` String
+    * `method` String
+    * `resourceType` String
+    * `timestamp` Double
+    * `fromCache` Boolean
+    * `error` String - The error description.
+
+The `listener` will be called with `listener(details)` when an error occurs.