{"id":14384795,"url":"https://github.com/aacerox/node-rest-client","last_synced_at":"2025-07-15T21:02:57.738Z","repository":{"id":7266163,"uuid":"8579002","full_name":"aacerox/node-rest-client","owner":"aacerox","description":"REST API client from node.js","archived":false,"fork":false,"pushed_at":"2024-09-30T20:45:18.000Z","size":384,"stargazers_count":377,"open_issues_count":45,"forks_count":132,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-06-29T10:04:00.435Z","etag":null,"topics":["json","nodejs","rest","rest-api","xml","xml-parser"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aacerox.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-03-05T12:12:22.000Z","updated_at":"2025-05-01T23:20:41.000Z","dependencies_parsed_at":"2024-06-18T12:16:49.555Z","dependency_job_id":"fa2a3dfe-b193-4ac1-aa59-a8deb8206b07","html_url":"https://github.com/aacerox/node-rest-client","commit_stats":{"total_commits":104,"total_committers":26,"mean_commits":4.0,"dds":0.3942307692307693,"last_synced_commit":"18edf68b59b65ad5157ac8d92affc22c229a5aeb"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/aacerox/node-rest-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aacerox%2Fnode-rest-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aacerox%2Fnode-rest-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aacerox%2Fnode-rest-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aacerox%2Fnode-rest-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aacerox","download_url":"https://codeload.github.com/aacerox/node-rest-client/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aacerox%2Fnode-rest-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265459571,"owners_count":23769410,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["json","nodejs","rest","rest-api","xml","xml-parser"],"created_at":"2024-08-28T18:01:40.713Z","updated_at":"2025-07-15T21:02:57.661Z","avatar_url":"https://github.com/aacerox.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# REST Client for Node.js\n[![npm version](https://badge.fury.io/js/node-rest-client.svg)](https://www.npmjs.com/package/node-rest-client)\n[![Build Status](https://travis-ci.org/olalonde/node-rest-client.svg?branch=master)](https://travis-ci.org/olalonde/node-rest-client)\n\n[![NPM](https://nodei.co/npm/node-rest-client.png?downloads=true)](https://nodei.co/npm/node-rest-client.png?downloads=true)\n\n## Features\n\nAllows connecting to any API REST and get results as js Object. The client has the following features:\n\n- Transparent HTTP/HTTPS connection to remote API sites.\n- Allows simple HTTP basic authentication.\n- Allows most common HTTP operations: GET, POST, PUT, DELETE, PATCH or any other method through custom connect method\n- Allows creation of custom HTTP Methods (PURGE, etc.)\n- Direct or through proxy connection to remote API sites.\n- Register remote API operations as own client methods, simplifying reuse.\n- Dynamic path and query parameters and request headers.\n- Improved Error handling mechanism (client or specific request)\n- Added support for compressed responses: gzip and deflate\n- Added support for follow redirects thanks to great [follow-redirects](https://www.npmjs.com/package/follow-redirects) package\n- Added support for custom request serializers (json,xml and url-encoded included by default)\n- Added support for custom response parsers (json and xml included by default)\n\n\n\n## Installation\n\n$ npm install node-rest-client\n\n## Usages\n\n### Simple HTTP GET\n\nClient has two ways to call a REST service: direct or using registered methods\n\n```javascript\nvar Client = require('node-rest-client').Client;\n\nvar client = new Client();\n\n// direct way\nclient.get(\"http://remote.site/rest/xml/method\", function (data, response) {\n\t// parsed response body as js object\n\tconsole.log(data);\n\t// raw response\n\tconsole.log(response);\n});\n\n// registering remote methods\nclient.registerMethod(\"jsonMethod\", \"http://remote.site/rest/json/method\", \"GET\");\n\nclient.methods.jsonMethod(function (data, response) {\n\t// parsed response body as js object\n\tconsole.log(data);\n\t// raw response\n\tconsole.log(response);\n});\n```\n\n### HTTP POST \n\nPOST, PUT or PATCH method invocation are configured like GET calls with the difference that you have to set \"Content-Type\" header in args passed to client method invocation:\n\n```javascript\n//Example POST method invocation\nvar Client = require('node-rest-client').Client;\n\nvar client = new Client();\n\n// set content-type header and data as json in args parameter\nvar args = {\n\tdata: { test: \"hello\" },\n\theaders: { \"Content-Type\": \"application/json\" }\n};\n\nclient.post(\"http://remote.site/rest/xml/method\", args, function (data, response) {\n\t// parsed response body as js object\n\tconsole.log(data);\n\t// raw response\n\tconsole.log(response);\n});\n\n// registering remote methods\nclient.registerMethod(\"postMethod\", \"http://remote.site/rest/json/method\", \"POST\");\n\nclient.methods.postMethod(args, function (data, response) {\n\t// parsed response body as js object\n\tconsole.log(data);\n\t// raw response\n\tconsole.log(response);\n});\n```\nIf no \"Content-Type\" header is set as client arg POST,PUT and PATCH methods will not work properly.\n\n\n### Passing args to registered methods\n\nYou can pass diferents args to registered methods, simplifying reuse: path replace parameters, query parameters, custom headers \n\n```javascript\nvar Client = require('node-rest-client').Client;\n\n// direct way\nvar client = new Client();\n\nvar args = {\n\tdata: { test: \"hello\" }, // data passed to REST method (only useful in POST, PUT or PATCH methods)\n\tpath: { \"id\": 120 }, // path substitution var\n\tparameters: { arg1: \"hello\", arg2: \"world\" }, // this is serialized as URL parameters\n\theaders: { \"test-header\": \"client-api\" } // request headers\n};\n\n\nclient.get(\"http://remote.site/rest/json/${id}/method\", args,\n\tfunction (data, response) {\n\t\t// parsed response body as js object\n\t\tconsole.log(data);\n\t\t// raw response\n\t\tconsole.log(response);\n\t});\n\n\n// registering remote methods\nclient.registerMethod(\"jsonMethod\", \"http://remote.site/rest/json/${id}/method\", \"GET\");\n\n\n/* this would construct the following URL before invocation\n *\n * http://remote.site/rest/json/120/method?arg1=hello\u0026arg2=world\n *\n */\nclient.methods.jsonMethod(args, function (data, response) {\n\t// parsed response body as js object\n\tconsole.log(data);\n\t// raw response\n\tconsole.log(response);\n});\n```\n\nYou can even use path placeholders in query string in direct connection:\n\n```javascript\nvar Client = require('node-rest-client').Client;\n\n// direct way\nvar client = new Client();\n\nvar args = {\n\tpath: { \"id\": 120, \"arg1\": \"hello\", \"arg2\": \"world\" },\t\n\theaders: { \"test-header\": \"client-api\" }\n};\n\nclient.get(\"http://remote.site/rest/json/${id}/method?arg1=${arg1}\u0026arg2=${arg2}\", args,\n\tfunction (data, response) {\n\t\t// parsed response body as js object\n\t\tconsole.log(data);\n\t\t// raw response\n\t\tconsole.log(response);\n\t});\n```\n\n###  HTTP POST and PUT methods\n\nTo send data to remote site using POST or PUT methods, just add a data attribute to args object:\n\n```javascript\nvar Client = require('node-rest-client').Client;\n\n// direct way\nvar client = new Client();\n\nvar args = {\n\tpath: { \"id\": 120 },\n\tparameters: { arg1: \"hello\", arg2: \"world\" },\n\theaders: { \"test-header\": \"client-api\" },\n\tdata: \"\u003cxml\u003e\u003carg1\u003ehello\u003c/arg1\u003e\u003carg2\u003eworld\u003c/arg2\u003e\u003c/xml\u003e\"\n};\n\nclient.post(\"http://remote.site/rest/xml/${id}/method\", args, function (data, response) {\n\t// parsed response body as js object\n\tconsole.log(data);\n\t// raw response\n\tconsole.log(response);\n});\n\n// registering remote methods\nclient.registerMethod(\"xmlMethod\", \"http://remote.site/rest/xml/${id}/method\", \"POST\");\n\n\nclient.methods.xmlMethod(args, function (data, response) {\n\t// parsed response body as js object\n\tconsole.log(data);\n\t// raw response\n\tconsole.log(response);\n});\n\n// posted data can be js object\nvar args_js = {\n\tpath: { \"id\": 120 },\n\tparameters: { arg1: \"hello\", arg2: \"world\" },\n\theaders: { \"test-header\": \"client-api\" },\n\tdata: { \"arg1\": \"hello\", \"arg2\": 123 }\n};\n\nclient.methods.xmlMethod(args_js, function (data, response) {\n\t// parsed response body as js object\n\tconsole.log(data);\n\t// raw response\n\tconsole.log(response);\n});\n```\n\n### Request/Response configuration\n\nIt's also possible to configure each request and response, passing its configuration as an\nadditional argument in method call.\n\n```javascript\nvar client = new Client();\n\n// request and response additional configuration\nvar args = {\n\tpath: { \"id\": 120 },\n\tparameters: { arg1: \"hello\", arg2: \"world\" },\n\theaders: { \"test-header\": \"client-api\" },\n\tdata: \"\u003cxml\u003e\u003carg1\u003ehello\u003c/arg1\u003e\u003carg2\u003eworld\u003c/arg2\u003e\u003c/xml\u003e\",\n\trequestConfig: {\n\t\ttimeout: 1000, //request timeout in milliseconds\n\t\tnoDelay: true, //Enable/disable the Nagle algorithm\n\t\tkeepAlive: true, //Enable/disable keep-alive functionalityidle socket.\n\t\tkeepAliveDelay: 1000 //and optionally set the initial delay before the first keepalive probe is sent\n\t},\n\tresponseConfig: {\n\t\ttimeout: 1000 //response timeout\n\t}\n};\n\n\nclient.post(\"http://remote.site/rest/xml/${id}/method\", args, function (data, response) {\n\t// parsed response body as js object\n\tconsole.log(data);\n\t// raw response\n\tconsole.log(response);\n});\n```\nIf you want to handle timeout events both in the request and in the response just add a new \"requestTimeout\"\nor \"responseTimeout\" event handler to clientRequest returned by method call.\n\n```javascript\nvar client = new Client();\n\n// request and response additional configuration\nvar args = {\n\tpath: { \"id\": 120 },\n\tparameters: { arg1: \"hello\", arg2: \"world\" },\n\theaders: { \"test-header\": \"client-api\" },\n\tdata: \"\u003cxml\u003e\u003carg1\u003ehello\u003c/arg1\u003e\u003carg2\u003eworld\u003c/arg2\u003e\u003c/xml\u003e\",\n\trequestConfig: {\n\t\ttimeout: 1000, //request timeout in milliseconds\n\t\tnoDelay: true, //Enable/disable the Nagle algorithm\n\t\tkeepAlive: true, //Enable/disable keep-alive functionalityidle socket.\n\t\tkeepAliveDelay: 1000 //and optionally set the initial delay before the first keepalive probe is sent\n\t},\n\tresponseConfig: {\n\t\ttimeout: 1000 //response timeout\n\t}\n};\n\n\nvar req = client.post(\"http://remote.site/rest/xml/${id}/method\", args, function (data, response) {\n\t// parsed response body as js object\n\tconsole.log(data);\n\t// raw response\n\tconsole.log(response);\n});\n\nreq.on('requestTimeout', function (req) {\n\tconsole.log('request has expired');\n\treq.abort();\n});\n\nreq.on('responseTimeout', function (res) {\n\tconsole.log('response has expired');\n\n});\n\n//it's usefull to handle request errors to avoid, for example, socket hang up errors on request timeouts\nreq.on('error', function (err) {\n\tconsole.log('request error', err);\n});\n```\n\n### Setup client to trust self-signed certificate with custom CA chain\nIn Internet mostly recommend solution to handle self-signed certificate is to just disable verification of server.\n**NEVER DO THAT IN PRODUCTION!**\nYou can do that only for development purpose - never in production because it puts great security risk on your business.\n\nHowever if you are connecting to a known server using self-signed certificate or a company server signed with corporate CA you can easily setup client to trust them and being secured in same moment.\nSo for example certificate chain:\n\n```\n+-- root-CA (self-signed)\n|   +-- department-CA (singed with root-CA)\n|       +-- domain (signed with department-CA)\n```\n\na solution is as follow:\n\n```javascript\nvar fs = required('fs');\nvar trustedCertificates = [\nfs.readFileSync('/PATH/TO/DOMAIN/CERTIFICATE'),\nfs.readFileSync('/PATH/TO/DEPARTMENT/CA'),\nfs.readFileSync('/PATH/TO/ROOT/CA')\n];\n\nvar options = {\n\tconnection: {\n\t\tca: trustedCertificates\n\t}\n};\nvar client = new Client(options);\n```\n\nNote that for readability format of certificate are skipped as multiple ones are supported.\n\n### Follows Redirect\nNode REST client follows redirects by default to a maximum of 21 redirects, but it's also possible to change follows redirect default config in each request done by the client\n```javascript\nvar client = new Client();\n\n// request and response additional configuration\nvar args = {\n\trequestConfig: {\n\t\tfollowRedirects:true,//whether redirects should be followed(default,true) \n\t\tmaxRedirects:10//set max redirects allowed (default:21)\n\t},\n\tresponseConfig: {\n\t\ttimeout: 1000 //response timeout\n\t}\n};\n\n```\n\n\n### Response Parsers\n\nYou can add your own response parsers to client, as many as you want. There are 2 parser types:\n\n- _**Regular parser**_: First ones to analyze responses. When a response arrives it will pass through all regular parsers, first parser whose `match` method return true will be the one to process the response. there can be as many regular parsers as you need. you can delete and replace regular parsers when it'll be needed.\n\n- _**Default parser**_: When no regular parser has been able to process the response, default parser will process it, so it's guaranteed that every response is processed. There can be only one default parser and cannot be deleted but it can be replaced adding a parser with `isDefault` attribute to true.\n\nEach parser - regular or default- needs to follow some conventions:\n\n* Must be and object\n\n* Must have the following attributes:\n\n    * `name`: Used to identify parser in parsers registry\n    \n    *  `isDefault`: Used to identify parser as regular parser or default parser. Default parser is applied when client cannot find any regular parser that match  to received response\n\n* Must have the following methods:\n\n    * `match(response)`: used to find which parser should be used with a response. First parser found will be the one to be used. Its arguments are:\n        1. `response`:`http.ServerResponse`: you can use any argument available in node ServerResponse, for example `headers`\n\n    * `parse(byteBuffer,nrcEventEmitter,parsedCallback)` : this method is where response body should be parsed and passed to client request callback. Its arguments are:\n        1. `byteBuffer`:`Buffer`: Raw response body that should be parsed as js object or whatever you need \n        2. `nrcEventEmitter`:`client event emitter`: useful to dispatch events during parsing process, for example error events\n        3. `parsedCallback`:`function(parsedData)`: this callback should be invoked when parsing process has finished to pass parsed data to request callback.\n\nOf course any other method or attribute needed for parsing process can be added to parser.\n\n```javascript\n// no \"isDefault\" attribute defined \nvar invalid = {\n\t\t\t   \"name\":\"invalid-parser\",\n\t\t\t   \"match\":function(response){...},\n\t\t\t   \"parse\":function(byteBuffer,nrcEventEmitter,parsedCallback){...}\n\t\t\t };\n\nvar validParser = {\n\t\t\t\t   \"name\":\"valid-parser\",\n\t\t\t\t   \"isDefault\": false,\n\t\t\t   \t   \"match\":function(response){...},\n\t\t\t       \"parse\":function(byteBuffer,nrcEventEmitter,parsedCallback){...},\n\t\t\t       // of course any other args or methods can be added to parser\n\t\t\t       \"otherAttr\":\"my value\",\n\t\t\t       \"otherMethod\":function(a,b,c){...}\n\t\t\t\t  };\t\t\t\n\nfunction OtherParser(name){\n\t   this.name: name,\n\t   this.isDefault: false,\n\t   this.match=function(response){...};\n\t   this.parse:function(byteBuffer,nrcEventEmitter,parsedCallback){...};\n\t\t\n}\n\nvar instanceParser = new OtherParser(\"instance-parser\");\n\n//valid parser complete example\n\nclient.parsers.add({\n\t\t\t\t\t\t\"name\":\"valid-parser\",\n\t\t\t\t\t\t\"isDefault\":false,\n\t\t\t\t\t\t\"match\":function(response){\n\t\t\t\t\t\t\t// only match to responses with  a test-header equal to \"hello world!\"\n\t\t\t\t\t\t\treturn response.headers[\"test-header\"]===\"hello world!\";\n\t\t\t\t\t\t},\t\t\t\t\t\t\t\n\t\t\t\t\t\t\"parse\":function(byteBuffer,nrcEventEmitter,parsedCallback){\n\t\t\t\t\t\t\t// parsing process\n\t\t\t\t\t\t\tvar parsedData = null;\n\t\t\t\t\t\t\ttry{\n\t\t\t\t\t\t\t\tparsedData = JSON.parse(byteBuffer.toString());\n\t\t\t\t\t\t\t\tparsedData.parsed = true;\n\n\t\t\t\t\t\t\t\t// emit custom event\n\t\t\t\t\t\t\t\tnrcEventEmitter('parsed','data has been parsed ' + parsedData);\n\n\t\t\t\t\t\t\t\t// pass parsed data to client request method callback\n\t\t\t\t\t\t\t\tparsedCallback(parsedData);\n\t\t\t\t\t\t\t}catch(err){\n\t\t\t\t\t\t\t\tnrcEmitter('error',err);\n\t\t\t\t\t\t\t};\t\t\t\t\t\t\n\n\t\t\t\t\t\t});\n\n```\n\nBy default and to maintain backward compatibility, client comes with 2 regular parsers and 1 default parser:\n\n- _**JSON parser**_: it's named 'JSON' in parsers registry and processes responses to js object. As in previous versions you can change content-types used to match responses by adding a  \"mimetypes\" attribute to client options.\n\n```javascript\nvar options = {\n\t\t\t\tmimetypes: {\n\t\t\t\t\t\tjson: [\"application/json\", \"application/my-custom-content-type-for-json;charset=utf-8\"]\n\t\t\t\t\t\t\n\t\t\t\t\t}\n\t\t\t\t};\n\nvar client = new Client(options);\t\t\t\t\n\n```\n\n- _**XML parser**_: it's named 'XML' in parsers registry and processes responses returned as XML documents to js object. As in previous versions you can change content-types used to match responses by adding a  \"mimetypes\" attribute to client options.\n\n```javascript\nvar options = {\n\t\t\t\tmimetypes: {\n\t\t\t\t\t\txml: [\"application/xml\", \"application/my-custom-content-type-for-xml\"]\t\t\t\t\t\t\n\t\t\t\t\t}\n\t\t\t\t};\n\nvar client = new Client(options);\n\n```\n\nAdditionally in this parser there's an attribute \"options\" where you can customize xml2js parser options. Please refer to [xml2js package](https://www.npmjs.com/package/xml2js) for valid parser options.\n\n```javascript\n\nvar client = new Client();\n\nclient.parsers.find(\"XML\").options= {\"explicitArray\":false, \"ignoreAttrs\":true};\n\n```\n\n\n- _**Default Parser**_: return responses as is, without any adittional processing.\n\n#### Parser Management\n\nClient can manage parsers through the following parsers namespace methods:\n\n* `add(parser)`: add a regular or default parser (depending on isDefault attribute value) to parsers registry. If you add a regular parser with the same name as an existing one, it will be overwritten\n\t\n\t1. `parser`: valid parser object. If invalid parser is added an 'error' event is dispatched by client.\n\n* `remove(parserName)`: removes a parser from parsers registry. If not parser found an 'error' event is dispatched by client.\n\t\n\t1. `parserName`: valid parser name previously added.\n\n* `find(parserName)`: find and return a parser searched by its name. If not parser found an 'error' event is dispatched by client.\n\t\n\t1. `parserName`: valid parser name previously added.\n\n* `getAll()`: return a collection of current regular parsers.\n\n* `getDefault()`: return the default parser used to process responses that doesn't match with any regular parser.\n\n* `clean()`: clean regular parser registry. default parser is not afected by this method.\n\n```javascript\nvar client = new Client();\n\nclient.parsers.add({\n\t\t\t\t   \"name\":\"valid-parser\",\n\t\t\t\t   \"isDefault\": false,\n\t\t\t   \t   \"match\":function(response){...},\n\t\t\t       \"parse\":function(byteBuffer,nrcEventEmitter,parsedCallback){...},\n\t\t\t       // of course any other args or methods can be added to parser\n\t\t\t       \"otherAttr\":\"my value\",\n\t\t\t       \"otherMethod\":function(a,b,c){...}\n\t\t\t\t  });\n\nvar parser = client.parsers.find(\"valid-parser\");\n\nvar defaultParser = client.parsers.getDefault();\n\nvar regularParsers = client.parsers.getAll();\t\n\nclient.parsers.clean();\t\t\t  \n\n\n```\n\n\n### Request Serializers\n\nYou can add your own request serializers to client, as many as you want. There are 2 serializer types:\n\n- _**Regular serializer**_: First ones to analyze requests. When a request is sent it will pass through all regular serializers, first serializer whose `match` method return true will be the one to process the request. there can be as many regular serializers as you need. you can delete and replace regular serializers when it'll be needed.\n\n- _**Default serializer**_: When no regular serializer has been able to process the request, default serializer will process it, so it's guaranteed that every request is processed. There can be only one default serializer and cannot be deleted but it can be replaced adding a serializer with `isDefault` attribute to true.\n\nEach serializer - regular or default- needs to follow some conventions:\n\n* Must be and object\n\n* Must have the following attributes:\n\n    * `name`: Used to identify serializer in serializers registry\n    \n    *  `isDefault`: Used to identify serializer as regular serializer or default serializer. Default serializer is applied when client cannot find any regular serializer that match  to sent request\n\n* Must have the following methods:\n\n    * `match(request)`: used to find which serializer should be used with a request. First serializer found will be the one to be used. Its arguments are:\n        1. `request`:`options passed to http.ClientRequest`: any option passed to a request through client options or request args, for example `headers`\n\n    * `serialize(data,nrcEventEmitter,serializedCallback)` : this method is where request body should be serialized before passing to client request callback. Its arguments are:\n        1. `data`:`args data attribute`: Raw request body as is declared in args request attribute that should be serialized.\n\n        2. `nrcEventEmitter`:`client event emitter`: useful to dispatch events during serialization process, for example error events\n        \n        3. `serializedCallback`:`function(serializedData)`: this callback should be invoked when serialization process has finished to pass serialized data to request callback.\n\nOf course any other method or attribute needed for serialization process can be added to serializer.\n\n```javascript\n// no \"isDefault\" attribute defined \nvar invalid = {\n\t\t\t   \"name\":\"invalid-serializer\",\n\t\t\t   \"match\":function(request){...},\n\t\t\t   \"serialize\":function(data,nrcEventEmitter,serializedCallback){...}\n\t\t\t };\n\nvar validserializer = {\n\t\t\t\t   \"name\":\"valid-serializer\",\n\t\t\t\t   \"isDefault\": false,\n\t\t\t   \t   \"match\":function(request){...},\n\t\t\t       \"serialize\":function(data,nrcEventEmitter,serializedCallback){...},\n\t\t\t       // of course any other args or methods can be added to serializer\n\t\t\t       \"otherAttr\":\"my value\",\n\t\t\t       \"otherMethod\":function(a,b,c){...}\n\t\t\t\t  };\t\t\t\n\nfunction OtherSerializer(name){\n\t   this.name: name,\n\t   this.isDefault: false,\n\t   this.match=function(request){...};\n\t   this.serialize:function(data,nrcEventEmitter,serializedCallback){...};\n\t\t\n}\n\nvar instanceserializer = new OtherSerializer(\"instance-serializer\");\n\n// valid serializer complete example\n\nclient.serializers.add({\n\t\t\t\t\t\t\"name\":\"example-serializer\",\n\t\t\t\t\t\t\"isDefault\":false,\n\t\t\t\t\t\t\"match\":function(request){\n\t\t\t\t\t\t\t// only match to requests with  a test-header equal to \"hello world!\"\n\t\t\t\t\t\t\treturn request.headers[\"test-header\"]===\"hello world!\";\n\t\t\t\t\t\t},\t\t\t\t\t\t\t\n\t\t\t\t\t\t\"serialize\":function(data,nrcEventEmitter,serializedCallback){\n\t\t\t\t\t\t\t// serialization process\n\t\t\t\t\t\t\tvar serializedData = null;\n\n\t\t\t\t\t\t\tif (typeof data === 'string'){\n\t\t\t\t\t\t\t\tserializedData = data.concat(\" I'm serialized!!\");\n\t\t\t\t\t\t\t}else if (typeof data === 'object'){\n\t\t\t\t\t\t\t\tserializedData = data;\n\t\t\t\t\t\t\t\tserializedData.state = \"serialized\"\n\t\t\t\t\t\t\t\tserializedData = JSON.stringify(serializedData);\n\t\t\t\t\t\t\t}\n\n\t\t\t\t\t\t\tnrcEventEmitter('serialized','data has been serialized ' + serializedData);\n\t\t\t\t\t\t\t// pass serialized data to client to be sent to remote API\n\t\t\t\t\t\t\tserializedCallback(serializedData);\n\n\t\t\t\t\t\t}\n\t\n})\n\n\n```\n\nBy default client comes with 3 regular serializers and 1 default serializer:\n\n- _**JSON serializer**_: it's named 'JSON' in serializers registry and serialize js objects to its JSON string representation. It will match any request sent  **exactly** with the following content types: \"application/json\",\"application/json;charset=utf-8\"\n\n\n- _**XML serializer**_: it's named 'XML' in serializers registry and serialize js objects to its XML string representation. It will match any request sent  **exactly** with the following content types: \"application/xml\",\"application/xml;charset=utf-8\",\"text/xml\",\"text/xml;charset=utf-8\"\n\nAdditionally in this parser there's an attribute \"options\" where you can customize xml2js serializer options. Please refer to [xml2js package](https://www.npmjs.com/package/xml2js) for valid builder options.\n\n```javascript\nvar client = new Client();\n\nclient.serializers.find(\"XML\").options={\"renderOpts\":{\"pretty\": true }};\n\n```\n\n- _**URL ENCODE serializer**_: it's named 'FORM-ENCODED' in serializers registry and serialize js objects to its FORM ENCODED string representation. It will match any request sent  **exactly** with the following content types: \"application/x-www-form-urlencoded\",\"multipart/form-data\",\"text/plain\"\n\n\n- _**Default serializer**_:  serialize request to its string representation, applying toString() method to data parameter.\n\n#### serializer Management\n\nClient can manage serializers through the following serializers namespace methods:\n\n* `add(serializer)`: add a regular or default serializer (depending on isDefault attribute value) to serializers registry.If you add a regular serializer with the same name as an existing one, it will be overwritten\n\t\n\t1. `serializer`: valid serializer object. If invalid serializer is added an 'error' event is dispatched by client.\n\n* `remove(serializerName)`: removes a serializer from serializers registry. If not serializer found an 'error' event is dispatched by client.\n\t\n\t1. `serializerName`: valid serializer name previously added.\n\n* `find(serializerName)`: find and return a serializer searched by its name. If not serializer found an 'error' event is dispatched by client.\n\t\n\t1. `serializerName`: valid serializer name previously added.\n\n* `getAll()`: return a collection of current regular serializers.\n\n* `getDefault()`: return the default serializer used to process requests that doesn't match with any regular serializer.\n\n* `clean()`: clean regular serializer registry. default serializer is not afected by this method.\n\n\n```javascript\nvar client = new Client();\n\nclient.serializers.add({\n\t\t\t\t\t\t\"name\":\"valid-serializer\",\n\t\t\t\t\t\t\"isDefault\":false,\n\t\t\t\t\t\t\"match\":function(request){\n\t\t\t\t\t\t\t// only match to requests with  a test-header equal to \"hello world!\"\n\t\t\t\t\t\t\treturn request.headers[\"test-header\"]===\"hello world!\";\n\t\t\t\t\t\t},\t\t\t\t\t\t\t\n\t\t\t\t\t\t\"serialize\":function(data,nrcEventEmitter,serializedCallback){\n\t\t\t\t\t\t\t// serialization process\n\t\t\t\t\t\t\tvar serializedData = null;\n\n\t\t\t\t\t\t\tif (typeof data === 'string'){\n\t\t\t\t\t\t\t\tserializedData = data.concat(\" I'm serialized!!\");\n\t\t\t\t\t\t\t}else if (typeof data === 'object'){\n\t\t\t\t\t\t\t\tserializedData = data;\n\t\t\t\t\t\t\t\tserializedData.state = \"serialized\"\n\t\t\t\t\t\t\t\tserializedData = JSON.stringify(serializedData);\n\t\t\t\t\t\t\t}\n\n\t\t\t\t\t\t\tnrcEventEmitter('serialized','data has been serialized ' + serializedData);\n\t\t\t\t\t\t\t// pass serialized data to client to be sent to remote API\n\t\t\t\t\t\t\tserializedCallback(serializedData);\n\n\t\t\t\t\t\t});\n\nvar serializer = client.serializers.find(\"valid-serializer\");\n\nvar defaultParser = client.serializers.getDefault();\n\nvar regularSerializers = client.serializers.getAll();\t\n\nclient.serializers.clean();\t\t\t  \n\n\n```\n\n### Connect through proxy\n\nJust pass proxy configuration as option to client.\n\n\n```javascript\nvar Client = require('node-rest-client').Client;\n\n// configure proxy\nvar options_proxy = {\n\tproxy: {\n\t\thost: \"proxy.foo.com\",\n\t\tport: 8080,\n\t\tuser: \"proxyuser\",\n\t\tpassword: \"123\",\n\t\ttunnel: true\n\t}\n};\n\nvar client = new Client(options_proxy);\n```\n\nclient has 2 ways to connect to target site through a proxy server: tunnel or direct request, the first one is the default option\nso if you want to use direct request you must set tunnel off.\n\n```javascript\nvar Client = require('node-rest-client').Client;\n\n// configure proxy\nvar options_proxy = {\n\tproxy: {\n\t\thost: \"proxy.foo.com\",\n\t\tport: 8080,\n\t\tuser: \"proxyuser\",\n\t\tpassword: \"123\",\n\t\ttunnel: false // use direct request to proxy\n\t}\n};\n\nvar client = new Client(options_proxy);\n```\n\n\n\n### Basic HTTP auth\n\nJust pass username and password or just username, if no password is required by remote site, as option to client. Every request done with the client will pass username and password or just username if no password is required as basic authorization header.\n\n```javascript\nvar Client = require('node-rest-client').Client;\n\n// configure basic http auth for every request\nvar options_auth = { user: \"admin\", password: \"123\" };\n\nvar client = new Client(options_auth);\n```\n\n### Options parameters\n\nYou can pass the following args when creating a new client:\n\n```javascript\nvar options = {\n\t// proxy configuration\n\tproxy: {\n\t\thost: \"proxy.foo.com\", // proxy host\n\t\tport: 8080, // proxy port\n\t\tuser: \"ellen\", // proxy username if required\n\t\tpassword: \"ripley\" // proxy pass if required\n\t},\n\t// aditional connection options passed to node http.request y https.request methods \n\t// (ie: options to connect to IIS with SSL)\t\n\tconnection: {\n\t\tsecureOptions: constants.SSL_OP_NO_TLSv1_2,\n\t\tciphers: 'ECDHE-RSA-AES256-SHA:AES256-SHA:RC4-SHA:RC4:HIGH:!MD5:!aNULL:!EDH:!AESGCM',\n\t\thonorCipherOrder: true\n\t},\n\t// will replace content-types used to match responses in JSON and XML parsers\n\tmimetypes: {\n\t\tjson: [\"application/json\", \"application/json;charset=utf-8\"],\n\t\txml: [\"application/xml\", \"application/xml;charset=utf-8\"]\n\t},\n\tuser: \"admin\", // basic http auth username if required\n\tpassword: \"123\", // basic http auth password if required\n\trequestConfig: {\n\t\ttimeout: 1000, //request timeout in milliseconds\n\t\tnoDelay: true, //Enable/disable the Nagle algorithm\n\t\tkeepAlive: true, //Enable/disable keep-alive functionalityidle socket.\n\t\tkeepAliveDelay: 1000 //and optionally set the initial delay before the first keepalive probe is sent\n\t},\n\tresponseConfig: {\n\t\ttimeout: 1000 //response timeout\n\t}\n};\n```\nNote that requestConfig and responseConfig options if set on client instantiation apply to all of its requests/responses\nand is only overriden by request or reponse configs passed as args in method calls.\n\n\n### Managing Requests\n\nEach REST method invocation returns a request object with specific request options and error, requestTimeout and responseTimeout event handlers.\n\n```javascript\nvar Client = require('node-rest-client').Client;\n\nvar client = new Client();\n\nvar args = {\n\trequesConfig: { timeout: 1000 },\n\tresponseConfig: { timeout: 2000 }\n};\n\n// direct way\nvar req1 = client.get(\"http://remote.site/rest/xml/method\", args, function (data, response) {\n\t// parsed response body as js object\n\tconsole.log(data);\n\t// raw response\n\tconsole.log(response);\n});\n\n// view req1 options\t\t\nconsole.log(req1.options);\n\n\nreq1.on('requestTimeout', function (req) {\n\tconsole.log(\"request has expired\");\n\treq.abort();\n});\n\nreq1.on('responseTimeout', function (res) {\n\tconsole.log(\"response has expired\");\n\n});\n\n\n// registering remote methods\nclient.registerMethod(\"jsonMethod\", \"http://remote.site/rest/json/method\", \"GET\");\n\nvar req2 = client.methods.jsonMethod(function (data, response) {\n\t// parsed response body as js object\n\tconsole.log(data);\n\t// raw response\n\tconsole.log(response);\n});\n\n// handling specific req2 errors\nreq2.on('error', function (err) {\n\tconsole.log('something went wrong on req2!!', err.request.options);\n});\n```\n\n###  Error Handling\n\n Now you can handle error events in two places: on client or on each request.\n\n```javascript\nvar client = new Client(options_auth);\n\n// handling request error events\nclient.get(\"http://remote.site/rest/xml/method\", function (data, response) {\n\t// parsed response body as js object\n\tconsole.log(data);\n\t// raw response\n\tconsole.log(response);\n}).on('error', function (err) {\n\tconsole.log('something went wrong on the request', err.request.options);\n});\n\n// handling client error events\nclient.on('error', function (err) {\n\tconsole.error('Something went wrong on the client', err);\n});\n```\n\n**NOTE:** _Since version 0.8.0 node does not contain node-waf anymore. The node-zlib package which node-rest-client make use of, depends on node-waf.Fortunately since version 0.8.0 zlib is a core dependency of node, so since version 1.0 of node-rest-client the explicit dependency to \"zlib\" has been removed from package.json. therefore if you are using a version below 0.8.0 of node please use a versión below 1.0.0 of \"node-rest-client\". _ \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faacerox%2Fnode-rest-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faacerox%2Fnode-rest-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faacerox%2Fnode-rest-client/lists"}