TheThing/koa-lite
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

updated request.md and response.md

Browse source
This commit is contained in:
bhanuc 2014-09-25 17:06:23 +05:30
parent e057ad1ced
commit 17e98e4e7d
2 changed files with 68 additions and 68 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

82
docs/api/request.md
View file

@ -6,74 +6,74 @@
## API ## API
### req.header ### request.header
Request header object. Request header object.
### req.headers ### request.headers
Request header object. Alias as `req.header`. Request header object. Alias as `request.header`.
### req.method ### request.method
Request method. Request method.
### req.method= ### request.method=
Set request method, useful for implementing middleware Set request method, useful for implementing middleware
such as `methodOverride()`. such as `methodOverride()`.
### req.length ### request.length
Return request Content-Length as a number when present, or `undefined`. Return request Content-Length as a number when present, or `undefined`.
### req.url ### request.url
Get request URL. Get request URL.
### req.url= ### request.url=
Set request URL, useful for url rewrites. Set request URL, useful for url rewrites.
### req.originalUrl ### request.originalUrl
Get request original URL. Get request original URL.
### req.path ### request.path
Get request pathname. Get request pathname.
### req.path= ### request.path=
Set request pathname and retain query-string when present. Set request pathname and retain query-string when present.
### req.querystring ### request.querystring
Get raw query string void of `?`. Get raw query string void of `?`.
### req.querystring= ### request.querystring=
Set raw query string. Set raw query string.
### req.search ### request.search
Get raw query string with the `?`. Get raw query string with the `?`.
### req.search= ### request.search=
Set raw query string. Set raw query string.
### req.host ### request.host
Get host (hostname:port) when present. Supports `X-Forwarded-Host` Get host (hostname:port) when present. Supports `X-Forwarded-Host`
when `app.proxy` is __true__, otherwise `Host` is used. when `app.proxy` is __true__, otherwise `Host` is used.
### req.hostname ### request.hostname
Get hostname when present. Supports `X-Forwarded-Host` Get hostname when present. Supports `X-Forwarded-Host`
when `app.proxy` is __true__, otherwise `Host` is used. when `app.proxy` is __true__, otherwise `Host` is used.
### req.type ### request.type
Get request `Content-Type` void of parameters such as "charset". Get request `Content-Type` void of parameters such as "charset".
@ -82,7 +82,7 @@ var ct = this.request.type;
// => "image/png" // => "image/png"
``` ```
### req.charset ### request.charset
Get request charset when present, or `undefined`: Get request charset when present, or `undefined`:
@ -91,7 +91,7 @@ this.request.charset
// => "utf-8" // => "utf-8"
``` ```
### req.query ### request.query
Get parsed query-string, returning an empty object when no Get parsed query-string, returning an empty object when no
query-string is present. Note that this getter does _not_ query-string is present. Note that this getter does _not_
@ -106,7 +106,7 @@ this.request.charset
} }
``` ```
### req.query= ### request.query=
Set query-string to the given object. Note that this Set query-string to the given object. Note that this
setter does _not_ support nested objects. setter does _not_ support nested objects.
@ -115,7 +115,7 @@ this.request.charset
this.query = { next: '/login' }; this.query = { next: '/login' };
``` ```
### req.fresh ### request.fresh
Check if a request cache is "fresh", aka the contents have not changed. This Check if a request cache is "fresh", aka the contents have not changed. This
method is for cache negotiation between `If-None-Match` / `ETag`, and `If-Modified-Since` and `Last-Modified`. It should be referenced after setting one or more of these response headers. method is for cache negotiation between `If-None-Match` / `ETag`, and `If-Modified-Since` and `Last-Modified`. It should be referenced after setting one or more of these response headers.
@ -134,32 +134,32 @@ if (this.fresh) {
this.body = yield db.find('something'); this.body = yield db.find('something');
``` ```
### req.stale ### request.stale
Inverse of `req.fresh`. Inverse of `request.fresh`.
### req.protocol ### request.protocol
Return request protocol, "https" or "http". Supports `X-Forwarded-Proto` Return request protocol, "https" or "http". Supports `X-Forwarded-Proto`
when `app.proxy` is __true__. when `app.proxy` is __true__.
### req.secure ### request.secure
Shorthand for `this.protocol == "https"` to check if a request was Shorthand for `this.protocol == "https"` to check if a request was
issued via TLS. issued via TLS.
### req.ip ### request.ip
Request remote address. Supports `X-Forwarded-For` when `app.proxy` Request remote address. Supports `X-Forwarded-For` when `app.proxy`
is __true__. is __true__.
### req.ips ### request.ips
When `X-Forwarded-For` is present and `app.proxy` is enabled an array When `X-Forwarded-For` is present and `app.proxy` is enabled an array
of these ips is returned, ordered from upstream -> downstream. When disabled of these ips is returned, ordered from upstream -> downstream. When disabled
an empty array is returned. an empty array is returned.
### req.subdomains ### request.subdomains
Return subdomains as an array. Return subdomains as an array.
@ -171,7 +171,7 @@ this.body = yield db.find('something');
If `app.subdomainOffset` is not set, this.subdomains is `["ferrets", "tobi"]`. If `app.subdomainOffset` is not set, this.subdomains is `["ferrets", "tobi"]`.
If `app.subdomainOffset` is 3, this.subdomains is `["tobi"]`. If `app.subdomainOffset` is 3, this.subdomains is `["tobi"]`.
### req.is(types...) ### request.is(types...)
Check if the incoming request contains the "Content-Type" Check if the incoming request contains the "Content-Type"
header field, and it contains any of the give mime `type`s. header field, and it contains any of the give mime `type`s.
@ -208,10 +208,10 @@ if (this.is('image/*')) {
Koa's `request` object includes helpful content negotiation utilities powered by [accepts](http://github.com/expressjs/accepts) and [negotiator](https://github.com/federomero/negotiator). These utilities are: Koa's `request` object includes helpful content negotiation utilities powered by [accepts](http://github.com/expressjs/accepts) and [negotiator](https://github.com/federomero/negotiator). These utilities are:
- `req.accepts(types)` - `request.accepts(types)`
- `req.acceptsEncodings(types)` - `request.acceptsEncodings(types)`
- `req.acceptsCharsets(charsets)` - `request.acceptsCharsets(charsets)`
- `req.acceptsLanguages(langs)` - `request.acceptsLanguages(langs)`
If no types are supplied, __all__ acceptable types are returned. If no types are supplied, __all__ acceptable types are returned.
@ -219,7 +219,7 @@ if (this.is('image/*')) {
In the case of missing accept headers where any type is acceptable, the first type will be returned. Thus, the order of types you supply is important. In the case of missing accept headers where any type is acceptable, the first type will be returned. Thus, the order of types you supply is important.
### req.accepts(types) ### request.accepts(types)
Check if the given `type(s)` is acceptable, returning the best match when true, otherwise `false`. The `type` value may be one or more mime type string Check if the given `type(s)` is acceptable, returning the best match when true, otherwise `false`. The `type` value may be one or more mime type string
such as "application/json", the extension name such as "application/json", the extension name
@ -269,7 +269,7 @@ switch (this.accepts('json', 'html', 'text')) {
} }
``` ```
### req.acceptsEncodings(encodings) ### request.acceptsEncodings(encodings)
Check if `encodings` are acceptable, returning the best match when true, otherwise `false`. Note that you should include `identity` as one of the encodings! Check if `encodings` are acceptable, returning the best match when true, otherwise `false`. Note that you should include `identity` as one of the encodings!
@ -293,7 +293,7 @@ this.acceptsEncodings();
Note that the `identity` encoding (which means no encoding) could be unacceptable if the client explicitly sends `identity;q=0`. Although this is an edge case, you should still handle the case where this method returns `false`. Note that the `identity` encoding (which means no encoding) could be unacceptable if the client explicitly sends `identity;q=0`. Although this is an edge case, you should still handle the case where this method returns `false`.
### req.acceptsCharsets(charsets) ### request.acceptsCharsets(charsets)
Check if `charsets` are acceptable, returning Check if `charsets` are acceptable, returning
the best match when true, otherwise `false`. the best match when true, otherwise `false`.
@ -316,7 +316,7 @@ this.acceptsCharsets();
// => ["utf-8", "utf-7", "iso-8859-1"] // => ["utf-8", "utf-7", "iso-8859-1"]
``` ```
### req.acceptsLanguages(langs) ### request.acceptsLanguages(langs)
Check if `langs` are acceptable, returning Check if `langs` are acceptable, returning
the best match when true, otherwise `false`. the best match when true, otherwise `false`.
@ -339,14 +339,14 @@ this.acceptsLanguages();
// => ["es", "pt", "en"] // => ["es", "pt", "en"]
``` ```
### req.idempotent ### request.idempotent
Check if the request is idempotent. Check if the request is idempotent.
### req.socket ### request.socket
Return the request socket. Return the request socket.
### req.get(field) ### request.get(field)
Return request header. Return request header.

54
docs/api/response.md
View file

@ -6,19 +6,19 @@
## API ## API
### res.header ### response.header
Response header object. Response header object.
### res.socket ### response.socket
Request socket. Request socket.
### res.status ### response.status
Get response status. By default, `res.status` is not set unlike node's `res.statusCode` which defaults to `200`. Get response status. By default, `response.status` is not set unlike node's `res.statusCode` which defaults to `200`.
### res.status= ### response.status=
Set response status via numeric code: Set response status via numeric code:
@ -83,20 +83,20 @@ __NOTE__: don't worry too much about memorizing these strings,
if you have a typo an error will be thrown, displaying this list if you have a typo an error will be thrown, displaying this list
so you can make a correction. so you can make a correction.
### res.length= ### response.length=
Set response Content-Length to the given value. Set response Content-Length to the given value.
### res.length ### response.length
Return response Content-Length as a number when present, or deduce Return response Content-Length as a number when present, or deduce
from `res.body` when possible, or `undefined`. from `this.body` when possible, or `undefined`.
### res.body ### response.body
Get response body. Get response body.
### res.body= ### response.body=
Set response body to one of the following: Set response body to one of the following:
@ -106,7 +106,7 @@ so you can make a correction.
- `Object` json-stringified - `Object` json-stringified
- `null` no content response - `null` no content response
If `res.status` has not been set, Koa will automatically set the status to `200` or `204`. If `response.status` has not been set, Koa will automatically set the status to `200` or `204`.
#### String #### String
@ -126,7 +126,7 @@ so you can make a correction.
The Content-Type is defaulted to application/json. The Content-Type is defaulted to application/json.
### res.get(field) ### response.get(field)
Get a response header field value with case-insensitive `field`. Get a response header field value with case-insensitive `field`.
@ -134,7 +134,7 @@ so you can make a correction.
var etag = this.get('ETag'); var etag = this.get('ETag');
``` ```
### res.set(field, value) ### response.set(field, value)
Set response header `field` to `value`: Set response header `field` to `value`:
@ -142,7 +142,7 @@ var etag = this.get('ETag');
this.set('Cache-Control', 'no-cache'); this.set('Cache-Control', 'no-cache');
``` ```
### res.set(fields) ### response.set(fields)
Set several response header `fields` with an object: Set several response header `fields` with an object:
@ -157,7 +157,7 @@ this.set({
Remove header `field`. Remove header `field`.
### res.type ### response.type
Get response `Content-Type` void of parameters such as "charset". Get response `Content-Type` void of parameters such as "charset".
@ -166,7 +166,7 @@ var ct = this.type;
// => "image/png" // => "image/png"
``` ```
### res.type= ### response.type=
Set response `Content-Type` via mime string or file extension. Set response `Content-Type` via mime string or file extension.
@ -178,11 +178,11 @@ this.type = 'png';
``` ```
Note: when appropriate a `charset` is selected for you, for Note: when appropriate a `charset` is selected for you, for
example `res.type = 'html'` will default to "utf-8", however example `response.type = 'html'` will default to "utf-8", however
when explicitly defined in full as `res.type = 'text/html'` when explicitly defined in full as `response.type = 'text/html'`
no charset is assigned. no charset is assigned.
### res.is(types...) ### response.is(types...)
Very similar to `this.request.is()`. Very similar to `this.request.is()`.
Check whether the response type is one of the supplied types. Check whether the response type is one of the supplied types.
@ -208,7 +208,7 @@ app.use(function *minifyHTML(next){
}); });
``` ```
### res.redirect(url, [alt]) ### response.redirect(url, [alt])
Perform a [302] redirect to `url`. Perform a [302] redirect to `url`.
@ -232,22 +232,22 @@ this.redirect('/cart');
this.body = 'Redirecting to shopping cart'; this.body = 'Redirecting to shopping cart';
``` ```
### res.attachment([filename]) ### response.attachment([filename])
Set `Content-Disposition` to "attachment" to signal the client Set `Content-Disposition` to "attachment" to signal the client
to prompt for download. Optionally specify the `filename` of the to prompt for download. Optionally specify the `filename` of the
download. download.
### res.headerSent ### response.headerSent
Check if a response header has already been sent. Useful for seeing Check if a response header has already been sent. Useful for seeing
if the client may be notified on error. if the client may be notified on error.
### res.lastModified ### response.lastModified
Return the `Last-Modified` header as a `Date`, if it exists. Return the `Last-Modified` header as a `Date`, if it exists.
### res.lastModified= ### response.lastModified=
Set the `Last-Modified` header as an appropriate UTC string. Set the `Last-Modified` header as an appropriate UTC string.
You can either set it as a `Date` or date string. You can either set it as a `Date` or date string.
@ -256,15 +256,15 @@ this.body = 'Redirecting to shopping cart';
this.response.lastModified = new Date(); this.response.lastModified = new Date();
``` ```
### res.etag= ### response.etag=
Set the ETag of a response including the wrapped `"`s. Set the ETag of a response including the wrapped `"`s.
Note that there is no corresponding `res.etag` getter. Note that there is no corresponding `response.etag` getter.
```js ```js
this.response.etag = crypto.createHash('md5').update(this.body).digest('hex'); this.response.etag = crypto.createHash('md5').update(this.body).digest('hex');
``` ```
### res.vary(field) ### response.vary(field)
Vary on `field`. Vary on `field`.