{
  "name": "rest",
  "version": "0.8.4",
  "main": "./rest.js",
  "dependencies": {
    "when": "~1"
  },
  "gitHead": "d7c94f9018efc67eea32f2ee76621f5a4ead491f",
  "readme": "Rest.js\n=======\n\nJust enough client, as you need it.  Make HTTP requests from a browser or Node.js applying the only the client features you need.  Configure a client once, and share it safely throughout your application.  Easily extend with interceptors that wrap the request and/or response, or MIME type converters for rich data formats.\n\n\nBuild Status\n------------\n\n<table>\n  <tr><td>Master</td><td><a href=\"http://travis-ci.org/s2js/rest\" target=\"_blank\"><img src=\"https://secure.travis-ci.org/s2js/rest.png?branch=master\" /></a></tr>\n  <tr><td>Development</td><td><a href=\"http://travis-ci.org/s2js/rest\" target=\"_blank\"><img src=\"https://secure.travis-ci.org/s2js/rest.png?branch=dev\" /></a></tr>\n</table>\n\n\nGetting Started\n---------------\n\nRest can be installed via [npm](https://npmjs.org/), [Bower](http://twitter.github.com/bower/), or from source.\n\nTo install without source:\n\n    $ npm install rest\n\nor\n\n    $ bower install rest\n\nFrom source:\n\n    $ npm install\n\nRest.js is designed to run in a browser environment, utilizing [AMD modules](https://github.com/amdjs/amdjs-api/wiki/AMD), or within [Node.js](http://nodejs.org/).  [curl](https://github.com/cujojs/curl) is highly recommended as an AMD loader, although any loader should work.\n\nAn ECMAScript 5 compatible environment is assumed.  Older browsers, ::cough:: IE, that do not support ES5 natively can be shimmed.  Any shim should work, although we've tested against cujo's [poly](https://github.com/cujojs/poly)\n\n\nUsage\n-----\n\nUsing Rest.js is easy.  The core clients provide limited functionality around the request and response lifecycle.  The input and response objects are normalized to support portability between browser and server environments.\n\nThe response from a client is a promise that is resolved when the remote request finishes.\n\nThe core client behavior can be augmented with interceptors.  An interceptor wraps the client and transforms the request and response.  For example: an interceptor may authenticate a request, or reject the promise if an error is encountered.  Interceptors may be combined to create a client with the desired behavior.  A configured interceptor acts just like a client.\n\n\n### Making a basic request: ###\n\n```javascript\ndefine(['rest'], function(client) {\n    client({ path: '/' }).then(function(response) {\n        console.log('response: ', response);\n    });\n});\n```\n\nIn this example, you can see that the request object is very simple, it just includes the path.  All of the attributes of a request are optional.\n\nThe response should look familiar as well, it contains all the fields you would expect, including the response headers (many clients ignore the headers).\n\n\n### Working with JSON: ###\n\nIf you're paying attention, you may have noticed that the response.entity in the previous example is a String.  Often we need to work with more complex data types.  For this, Rest supports a rich set of MIME type conversions with the `mime` interceptor.  The correct converter will automatically be chosen based on the Content-Type response header.  Custom converts can be registered for a MIME type, more on that later...\n\n```javascript\ndefine(['rest/interceptor/mime'], function(mime) {\n    var client = mime();\n    client({ path: '/data.json' }).then(function(response) {\n        console.log('response: ', response);\n    });\n});\n```\n\nBefore an interceptor can be used, it needs to be configured.  In this case, we will accept the default configuration, and obtain a client.  Now when we see the response, the entity will be a JS object instead of a String.\n\n\n### Composing Interceptors: ###\n\n```javascript\ndefine(['rest/interceptor/mime', 'rest/interceptor/errorCode'], function(mime, errorCode) {\n    var client = mime();\n    client = errorCode(client, { code: 500 });\n    client({ path: '/data.json' }).then(\n        function(response) {\n            console.log('response: ', response);\n        },\n        function(response) {\n            console.error('response error: ', response);\n        }\n    );\n});\n```\n\nIn this example, we take the client create by the `mime` interceptor, and wrap it in the `errorCode` interceptor.  The errorCode interceptor can accept a configuration object that indicates what status codes should be considered an error.  In this case we override the default value of <=400, to only reject with 500 or greater status code.\n\nSince the errorCode interceptor can reject the response promise, we also add a second handler function to receive the response for requests in error.\n\nClients can continue to be composed with interceptors as needed.  At any point the client as configured can be shared.  It is safe to share clients and allow other parts of your application to continue to compose other clients around the shared core.  Your client is protected from additional interceptors that other parts of the application may add.\n\n\n### Custom MIME Converters: ###\n\n```javascript\ndefine(['rest/mime/registry'], function(registry) {\n   registry.register('application/vnd.com.example', {\n       read: function(str) {\n           var obj;\n           // do string to object conversions\n           return obj;\n       },\n       write: function(obj) {\n           var str;\n           // do object to string conversions\n           return str;\n       }\n   });\n});\n```\n\nRegistering a custom converter is a simple as calling the register function on the mime registry with the type and converter.  A converter has just two methods: `read` and `write`.  Read converts a String to a more complex Object.  Write converts an Object back into a String to be sent to the server.  HTTP is fundamentally a text based protocol after all.\n\nBuilt in converters are available under `rest/mime/type/{type}`, as an example, JSON support is located at `rest/mime/type/application/json`.  You never need to know this as a consumer, but it's a good place to find examples.\n\n\nReporting Issues\n----------------\n\nPlease report issues on [GitHub](https://github.com/s2js/rest/issues).  Include a brief description of the error, information about the runtime (including shims) and any error messages.\n\nFeature requests are also welcome.\n\n\nRunning the Tests\n-----------------\n\nThe test suite can be run in two different modes: in node, or in a browser.  We use [npm](https://npmjs.org/) and [Buster.JS](http://busterjs.org/) as the test driver, buster is installed automatically with other dependencies.\n\nBefore running the test suite for the first time:\n\n    $ npm install\n\nTo run the suite in node:\n\n    $ npm test\n\nTo run the suite in a browser:\n\n    $ npm start\n    browse to http://localhost:8282/ in the browser(s) you wish to test.  It can take a few seconds to start.\n\n\nContributors\n------------\n\n- Scott Andrews <andrewss@vmware.com>\n- Jeremy Grelle <jgrelle@vmware.com>\n\nPlease see CONTRIBUTING.md for details on how to contribute to this project.\n\n\nCopyright\n---------\n\nIntegration is made available under the MIT license.  See LICENSE.txt for details.\n\nCopyright (c) 2012-2013 VMware, Inc. All Rights Reserved.\n\nVMware, Inc.\n3401 Hillview Avenue\nPalo Alto, CA 94304\n\n\nChange Log\n----------\n\n0.8.4\n- Bower installable, with dependencies\n- node client's response.raw includes ClientResquest and ClientResponse objects\n- basicAuth interceptor correctly indicates auth method\n\n0.8.3\n- moving from the 'scothis' to the 's2js' organization, no functional changes\n\n0.8.2\n- requests may be canceled\n- timeout incerceptor that cancels the request unless it finishes before the timeout\n- retry interceptor handles error respones by retrying the request after an elapsed period\n- error interceptor handlers may recover from errors, a rejected promise must be returned in order to preserve the error state\n- response objects, with an error property, are used for client errors instead of the thrown value\n- interceptor response handlers recieve the interceptor's client rather then the next client in the chain\n- interceptor request handlers may provide a response\n- convert modules to UMD format; no functional impact\n- replaced rest/util/base64 with an MIT licenced impl; no functional impact\n\n0.8.1\n- fixed bug where http method may be overwritten\n\n0.8.0\n- npm name change 'rest-template' -> 'rest'\n- introduced experimental HATEOAS support\n- introduced 'location' interceptor which follows Location response headers, issuing a GET for the specified URL\n- default method to POST when request contains an entity\n- response handlers now have access to the request client to issue subsequent requests\n- interceptors may specify their default client\n- renamed `rest/interceptor/_base` to `rest/interceptor`\n\n0.7.5\n- Initial release, everything is new\n",
  "readmeFilename": "README.md",
  "_id": "rest@0.8.4",
  "description": "Rest.js =======",
  "repository": {
    "type": "git",
    "url": "git://github.com/cujojs/rest.git"
  }
}