Add instructions for HTTP redirecting

docs/api/app.md

@@ -94,7 +94,8 @@ crawlers to update their index like this:
 $app->redirect('/blog.html', '/blog', React\Http\Message\Response::STATUS_MOVED_PERMANENTLY);
 ```
 
-See [response status codes](response.md#status-codes) for more details.
+See [response status codes](response.md#status-codes) and [HTTP redirects](response.md#http-redirects)
+for more details.
 
 ## Controllers
 

docs/api/response.md

@@ -263,6 +263,36 @@ Hello wörld!
 > });
 > ```
 
+## HTTP Redirects
+
+To redirect incoming HTTP requests to a new location you can define your HTTP
+response like this:
+
+```php
+<?php
+
+// …
+
+$app->get('/blog.html', function () {
+    return new React\Http\Message\Response(
+        React\Http\Message\Response::STATUS_FOUND,
+        [
+            'Location' => '/blog'
+        ]
+    );
+});
+```
+
+Redirect responses have a status code in the 3xx range, and a [`Location`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location)
+response header holding the URL to redirect to. When a Browser or a search engine
+crawler receives a redirect, they will automatically follow the new URL provided
+in the `Location` header.
+
+See [response status codes](#status-codes) for more details.
+
+You can also use the [redirect helper method](https://framework-x.org/docs/api/app/#redirects)
+for simpler use cases.
+
 ## HTTP caching
 
 HTTP caching can be used to significantly improve the performance of web