A connect middleware for parsing incoming XML data. It converts the received XML data structure into a JSON-object. The XML bodyparser middleware works in any connect- or express-based nodejs application.
For those rare cases when you have to parse incoming raw xml-body requests. This middleware works with any connect- or express-based nodejs application.
Description
Admittedly, having to deal with XML data has become less common in recent years. Still, there are services and APIs using this format. The middleware is based on the connect-json middleware as a blueprint.
There is a similar xml bodyparser module available, but you might appreciate some notable differences:
- Custom configuration options how to deal with XML data.
- Attempt to parse data only once, even if middleware is called multiple times.
- Skip data parsing immediately if no req-body has been sent.
- Accept any XML-based content-type, e.g.
application/rss+xml - No dependency on coffeescript keeping dependencies to a minimum.
Installation
Utilize npm by typing npm install express-xml-bodyparser --save in your projects root folder and your good to go.
Configuration
You can pass configuration options into the XML parser middleware. They’re exactly the same options you would use for xml2js, which this middleware relies on. For further details look at all available configuration options.
Without specifying custom options, the middleware applies some opionated defaults meant to normalize the resulting json object properties. All whitespace in text nodes will be trimmed, property and tag names will be lowercased. The parser will always return node lists explicitly cast to Array.
NOTE: Custom options will be merged with aforementioned opionated defaults, so in case you want to use xml2js defaults, you will have to specify the following:
var xml2jsDefaults = {
explicitArray: false,
normalize: false,
normalizeTags: false,
trim: true
}
This change appeared in v0.1.0, older versions would merge options against xml2js’s default options.
Usage
You can either use express-xml-bodyparser at application level, or for specific routes only.
Here is an example of an express application with default settings:
var express = require('express'),
app = express(),
http = require('http'),
server = http.createServer(app),
xmlparser = require('express-xml-bodyparser');
// .. other middleware ...
app.use(express.json());
app.use(express.urlencoded());
app.use(xmlparser());
// ... other middleware ...
app.post('/receive-xml', function(req, res, next) {
// req.body contains the parsed xml
});
server.listen(1337);
If you wanted to use express-xml-bodyparser for specific routes only, you would do something like this:
app.post('/receive-xml', xmlparser({trim: false, explicitArray: false}), function(req, res, next) {
// check req.body
});
Above example demonstrates how to pass custom options to the XML parser.
Customize mime-type detection
If you want to customize the regular expression that checks whether the xmlparser should do its work or not, you can provide your own by overloading the xmlparser.regexp property, like so:
var xmlparser = require('express-xml-bodyparser');
xmlparser.regexp = /^text\/xml$/i;
Doing so, will allow you to restrict XML parsing to custom mime-types only. Thanks to @ophentis for the suggestion. Just make sure your regular expression actually matches mime-types you’re interested in. The feature is available since version v0.0.5.
IMPORTANT In versions v0.2.x custom regular expressions were ignored in mime-type parsing. The issue has been fixed in v0.3.0. If you need/rely on this feature, please upgrade to a newer version. Many thanks to @dirksen who discovered this issue.