diff --git a/docs/api/index.md b/docs/api/index.md index efa47d1..0325b43 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -1,8 +1,28 @@ # Application - A Koa application is not a 1-to-1 representation of an HTTP server, - as one or more Koa applications may be mounted together to form larger - applications, with a single HTTP server. + A Koa application is an object containing an array of middleware generator functions + which are composed and executed in a stack-like manner upon request. Koa is similar to many + other middleware systems that you may have encountered such as Ruby's Rack, Connect, and so on - + however a key design decision was made to provide high level "sugar" at the otherwise low-level + middleware layer. This improves interoperability, robustness, and makes writing middleware much + more enjoyable. + + This includes methods for common tasks like content-negotation, cache freshness, proxy support, and redirection + among others. Despite supplying a reasonably large number of helpful methods Koa maintains a small footprint, as + no middleware are bundled. + + The obligatory hello world application: + +```js +var koa = require('koa'); +var app = koa(); + +app.use(function *(){ + this.body = 'Hello World'; +}); + +app.listen(3000); +``` ## Settings @@ -18,6 +38,10 @@ ## app.listen(...) + A Koa application is not a 1-to-1 representation of an HTTP server, + as one or more Koa applications may be mounted together to form larger + applications, with a single HTTP server. + Create and return an HTTP server, passing the given arguments to `Server#listen()`. These arguments are documented on [nodejs.org](http://nodejs.org/api/http.html#http_server_listen_port_hostname_backlog_callback). The following is a useless Koa application bound to port `3000`: