Revise API handler documentation

docs/api-handlers.md

@@ -3,11 +3,7 @@ id: api-handlers
 title: API Handlers
 ---
 
-Use API Handlers to provide your reSolve server with the capability to handle arbitrary HTTP requests.
-
-## API Reference
-
-ReSolve API handlers have the following general structure:
+Use API Handlers to provide your reSolve server with the capability to handle arbitrary HTTP requests. ReSolve API handlers have the following general structure:
 
 ##### common/api-handlers/my-api-handler.js:
 
@@ -19,7 +15,7 @@ export default async (req, res) => {
 
 The handler function takes two parameters - the [request](#request) and [response](#response).
 
-### Request
+## Request
 
 The `req` object represents the HTTP request. This object exposes properties that provide access to the request query string, parameters, body, HTTP headers, etc.
 
@@ -32,12 +28,26 @@ The request provides the following interface:
   path: String,
   body: String,
   cookies: Object<key, value>,cd
-  headers: Object<key, value>,
-  query: Object<key, value>
+  <key, value>,
+  query: Object<key, value>,
+  resolve: Object<key, value>
 }
 ```
 
-### Response
+The request's `resolve` field is a reSolve context object that provides access to reSolve API and metadata. Through this object, you can use reSolve-specific API:
+
+```js
+const getPersonalKey = async (req, res) => {
+    await req.resolve.executeCommand({
+      ...
+    });
+    res.end();
+  }
+```
+
+> **Note:** The `resolve` object contains resources, such as database connections, that are disposed after the API handler completes to prevent leaks. For this reason, you should not use the `resolve` object in code with delayed execution that may run after the API handler completes.
+
+## Response
 
 The `res` object represents the server's response to the HTTP request.
 
@@ -58,7 +68,7 @@ The response object provides the following interface:
 }
 ```
 
-### Configuration
+## Configuration
 
 An API handler should be registered in the `apiHandlers` section of the application's configuration file.
 
@@ -90,7 +100,7 @@ Refer to the [Application Configuration](application-configuration) topic for mo
 
 ## Implementation Examples
 
-- Send Text
+##### Send Text
 
 ```js
 export default async (req, res) => {
@@ -100,7 +110,7 @@ export default async (req, res) => {
 }
 ```
 
-- Send JSON
+##### Send JSON
 
 ```js
 export default async (req, res) => {
@@ -113,7 +123,7 @@ export default async (req, res) => {
 }
 ```
 
-- Send File
+##### Send File
 
 ```js
 export default async (req, res) => {
@@ -125,7 +135,7 @@ export default async (req, res) => {
 }
 ```
 
-- Set Cookies
+##### Set Cookies
 
 ```js
 export default async (req, res) => {
@@ -135,15 +145,15 @@ export default async (req, res) => {
 }
 ```
 
-- Redirect
+##### Redirect
 
 ```js
 export default async (req, res) => {
   res.redirect('/settings')
 }
 ```
 
-- Custom status
+##### Custom status
 
 ```js
 export default async (req, res) => {

docs/api-reference.md

@@ -370,6 +370,50 @@ const data = await store.find('Entries', {
 })
 ```
 
+## API Handler Interface
+
+An API handler function has the following structure:
+
+```js
+export default async (req, res) => {
+  // ...
+}
+```
+
+The handler receives a request and response objects. See the sections below for the information on the API exposed through these objects.
+
+### Request
+
+The request objects exposes the following fields:
+
+| field   | description                                                                        |
+| ------- | ---------------------------------------------------------------------------------- |
+| resolve | The reSolve context object that provides access to reSolve API and metadata.       |
+| adapter | The name of the adapter used to handle the request (`"express"` or `"awslambda"`). |
+| method  | The request's HTTP method.                                                         |
+| path    | The request URL's path part.                                                       |
+| body    | The request body.                                                                  |
+| cookies | An object that contains cookies as key-value pairs.                                |
+| headers | An object that contains the request's HTTP headers as key-value pairs.             |
+| query   | An object that contains the request's query string parameters as key-value pairs.  |
+
+### Response
+
+The request objects exposes the following functions:
+
+| function                             | description                                 |
+| ------------------------------------ | ------------------------------------------- |
+| status(code)                         | Specifiers the response status code.        |
+| getHeader(key)                       | Get a response header by key.               |
+| setHeader(key, value)                | Sets a response header.                     |
+| text([content] [, encoding])         | Specifies content for a text-type response  |
+| json([content])                      | Specifies content for a JSON-type response. |
+| end([content] [, encoding])          | Ends the response process.                  |
+| file(content, filename [, encoding]) | Specifies a file to write to response.      |
+| redirect([status,] path)             | Specifies the redirect path.                |
+| cookie(name, value [, options])      | Specifies cookies to send to the client.    |
+| clearCookie(name [, options])        | Clears a cookie from the response.          |
+
 ## Saga API
 
 A saga's event handler receives an object that provides access to the saga-related API. This API includes the following objects: