Skip to content
Browse files

Added the start of markdown docs

  • Loading branch information...
1 parent 42d0ab9 commit aa6acd64ce3dfd3cd94d09f69ec88929af83b4b0 @tj tj committed
Showing with 184 additions and 3 deletions.
  1. +3 −3 Readme.md
  2. +181 −0 docs/index.md
View
6 Readme.md
@@ -1,7 +1,7 @@
-# superagent
+# SuperAgent
- Super-agent is an elegant, small (~1.7kb compressed), progressive client-side HTTP request library.
+ SuperAgent is an elegant, small (~1.7kb compressed), progressive client-side HTTP request library.
![super agent](http://f.cl.ly/items/3d282n3A0h0Z0K2w0q2a/Screenshot.png)
@@ -98,7 +98,7 @@ request.post('/api/pet', cat, function(res){
## Browser support
- Actively tested in:
+ Actively tested with:
- Firefox 5.x
- Safari 5.x
View
181 docs/index.md
@@ -0,0 +1,181 @@
+
+# SuperAgent
+
+ Super Agent is light-weight progressive ajax API crafted for flexibility, readability, and a low learning curve after being frustrated with many of the existing request APIs.
+
+ request
+ .post('/api/pet')
+ .data({ name: 'Manny', species: 'cat' })
+ .set('X-API-Key', 'foobar')
+ .set('Accept', 'application/json')
+ .end(function(res){
+ if (res.ok) {
+ alert('yay got ' + JSON.stringify(res.body));
+ } else {
+ alert('Oh no! error ' + res.text);
+ }
+ });
+
+## Request basics
+
+ A request can be initiated by invoking the appropriate method on the `request` object, then calling `.end()` to send the request. For example a simple GET request:
+
+ request
+ .get('/search')
+ .end(function(res){
+
+ });
+
+ The __node__ client may also provide absolute urls:
+
+ request
+ .get('http://example.com/search')
+ .end(function(res){
+
+ });
+
+ __DELETE__, __HEAD__, __POST__, __PUT__ and other __HTTP__ verbs may also be used, simply change the method name:
+
+ request
+ .head('/favicon.ico')
+ .end(function(res){
+
+ });
+
+ __DELETE__ is a special-case, as it's a reserved word, so the method is named `.del()`:
+
+ request
+ .del('/user/1')
+ .end(function(res){
+
+ });
+
+### Crafting requests
+
+ SuperAgent's flexible API gives you the granularity you need, _when_ you need, yet more concise variations help reduce the amount of code necessary. For example the following GET request:
+
+ request
+ .get('/search')
+ .end(function(res){
+
+ });
+
+ Could also be defined as the following, where a callback is given to the HTTP verb method:
+
+ request
+ .get('/search', function(res){
+
+ });
+
+ Taking this further the default HTTP verb is __GET__ so the following works as well:
+
+ request('/search', function(res){
+
+ });
+
+ This applies to more complicated requests as well, for example the following __GET__ request with a query-string can be written in the chaining manner:
+
+ request
+ .get('/search')
+ .data({ query: 'tobi the ferret' })
+ .end(function(res){
+
+ });
+
+ Or one may pass the query-string object to `.get()`:
+
+ request
+ .get('/search', { query: 'tobi the ferret' })
+ .end(function(res){
+
+ });
+
+ Taking this even further the callback may be passed as well:
+
+ request
+ .get('/search', { query: 'tobi the ferret', function(res){
+
+ });
+
+## Setting header fields
+
+ Setting header fields is simple, invoke `.set()` with a field name and value:
+
+ request
+ .get('/search')
+ .set('API-Key', 'foobar')
+ .set('Accept', 'application/json')
+ .end(callback);
+
+## GET requests
+
+ The `.data()` method accepts objects, which when used with the __GET__ method will form a query-string. The following will produce the path `/search?query=Manny&range=1..5&order=desc`.
+
+ request
+ .get('/search')
+ .data({ query: 'Manny' })
+ .data({ range: '1..5' })
+ .data({ order: 'desc' })
+ .end(function(res){
+
+ });
+
+ The `.data()` method accepts strings as well:
+
+ request
+ .get('/querystring')
+ .data('search=Manny&range=1..5')
+ .end(function(res){
+
+ });
+
+### POST / PUT requests
+
+ A typical JSON __POST__ request might look a little like the following, where we set the Content-Type header field appropriately, and "write" some data, in this case just a JSON string.
+
+ request.post('/user')
+ .set('Content-Type', 'application/json')
+ .data('{"name":"tj","pet":"tobi"})
+ .end(callback)
+
+ Since JSON is undoubtably the most common, it's the _default_! The following example is equivalent to the previous.
+
+ request.post('/user')
+ .data({ name: 'tj', pet: 'tobi' })
+ .end(callback)
+
+ Or using multiple `.data()` calls:
+
+ request.post('/user')
+ .data({ name: 'tj' })
+ .data({ pet: 'tobi' })
+ .end(callback)
+
+ SuperAgent formats are extensible, however by default "json" and "form-data" are supported. To send the data as `application/x-www-form-urlencoded` simply invoke `.type()` with "form-data", where the default is "json". This request will POST the body "name=tj&pet=tobi".
+
+ request.post('/user')
+ .type('form-data')
+ .data({ name: 'tj' })
+ .data({ pet: 'tobi' })
+ .end(callback)
+
+## Response properties
+
+ Many helpful flags and properties are set on the `Response` object, ranging from the response text, parsed response body, header fields, status flags and more.
+
+### Response text
+
+ The `res.text` property contains the unparsed response body string.
+
+### Response body
+
+ Much like SuperAgent can auto-serialize request data, it can also automatically parse it. When a parser is defined for the Content-Type, it is parsed, which by default includes "application/json" and "application/x-www-form-urlencoded". The parsed object is then available via `res.body`.
+
+### Response header fields
+
+ The `res.header` contains an object of parsed header fields, lowercasing field names much like node does. For example `res.header['content-length']`.
+
+### Response Content-Type
+
+ The Content-Type response header is special-cased, providing `res.contentType`, which is void of the charset (if any). For example the Content-Type of "text/html; charset=utf8" will provide "text/html" as `res.contentType`, and the `res.charset` property would then contain "utf8".
+

0 comments on commit aa6acd6

Please sign in to comment.
Something went wrong with that request. Please try again.