Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including rss_parser_api with all npm packages installed. Try it out:

var rssParserApi = require("rss_parser_api")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

rss_parser_api v1.0.2

Microservice that parses an RSS/Atom URL


npm node


GET /items

Returns the RSS/Atom feed's items parsed as JSON.

Each item will include its enclosure's MD5 checksum as a checksum property.


  • feed {url} (required): RSS/Atom URL to parse
  • verbose {boolean} (default: true): whether items' whole information should be included
  • pretty {boolean} (default: true): whether to indent the JSON response
  • checksum {boolean} (default: true): whether checksums should be included. Specifying false significantly speed up the request.

Success response

  "data": [
      "title": "24. Podcast title",
      "description": "Description of this podcast",
      "checksum": "95ceab9bcd3c1c27b268a6375d9a8032",

Error responses

The following type are available:

  • INPUT_VALIDATION (400): wrong parameters. This includes supplying a document containing a URL to a feed or media file that does not exist or has syntax errors.
  • FEED (400): feed is not valid XML
  • NOT_FOUND (404): wrong request URL
  • METHOD_NOT_ALLOWED (405): unsupported HTTP method
  • UNKNOWN (500): an unknown server-side error occurred

GET /id3

Returns the MP3 file's ID3 tags.


  • url {url} (required): URL to an MP3 file
  • pretty {boolean} (default: true): whether to indent the JSON response

Success response

  "data": {
    "TIT2": {
      "id": "TIT2",
      "size": 14,
      "description": "Title/songname/content description",
      "data": "24. Summer hit"

Error responses

The same type as GET /items are available except FEED.

Starting the server

Run npm install then npm start.

To run in dev mode, run npm run watch.

To perform linting and testing, run npm test.


The following configuration properties can be set using environment variables:

  • HOST (default: localhost)
  • PORT (default: 80)
  • NODE_ENV (default: development)

Parameters design

We allow REST parameters both as:

  • query variables, e.g. ?feed=URL, because it is the most common/expected practice and it is easier for debugging. Values must be URI encoded.
  • HTTP headers, e.g. X-Rss-Parser-Feed: URL, because it is the most semantically correct. According to W3C TAG specs, URLs should be used only for resource identification, not for query logic. Protocol headers should be used for that instead.


Syndication formats

The following formats are supported: RSS 2.0, RSS 1.0, RSS 0.90, Atom 1.0, Atom 0.3, RDF Feed.

Moreover MRSS, itunes and Dublin core properties are supported.

Response streaming

Calculating checksums with GET /items is slow because each media file must be downloaded first. To mitigate this:

  • the response is streamed with HTTP/1.1 chunked transfer encoding.
  • media files are downloaded in parallel as soon as their URI is available. However the order of the items in the response is properly kept.


Also response body are compressed with deflate and gzip.

Furthermore caching is being performed:

  • between the server and the URLs being fetched
  • between the client and the server as both conditional and unconditional HTTP caching


Logs are printed on console as JSON, one message per line. This is to dissociate logs creation from logs transport.

The three following types of logs are performed.


When the server starts.

  "type": "start",
  "level": "log",
  "message": "Server listening at http://localhost:5001"


When a client makes an HTTP request, successful or not.

  "type": "request",
  "level": "log",
  "statusCode": 200,
  "method": "GET",
  "path": "/id3",
  "query": { "url":"file.mp3" },
  "ip": ""


When a client makes an HTTP request that fails.

  "type": "error",
  "level": "error",
  "error": { ... }

The error property has the same signature as the error response

Error handling

Error responses follow the RFC 7807 "problem details":

  "error": {
    "status": 404,
    "type": "NOT_FOUND",
    "description": "Route '/id33' does not exist",
    "instance": "http://localhost:5001/id33",
    "details": "Error: Route '/id33' does not exist\n    at ..."

Stack traces are only included when NODE_ENV is development.

Performance monitoring

The X-Response-Time HTTP header is set on each response.

REST design

The method GET is used, as opposed to POST, since the calls are safe.

Semantic HTTP response headers are included:

  • Last-Modified based on the feed's <lastPublishedDate>, <modified> or <updated>
  • Link: <URI>; rel="alternate"; type="application/rss+xml"


Basic security is provided by helmet.


This project follows the 12-factor app principles.

Universal JavaScript

Most dependencies work on the browser as well, so the core functions of this microservice can easily be ported client-side.


Please use latest Node version.

Missing features

The following features could be added (in priority order):

  • pagination
  • improving the security: HTTPS, authorization, more server limits, etc.
  • HTTP/2
  • DevOps, Continuous Integration/Deployment
  • using a distributed key-value store for server-side caching
  • filtering, e.g. with a filter parameter
  • sorting, e.g. with an order parameter
  • request timeout
  • server push (WebSub) or long polling
  • improving the API documentation, e.g. with a separate website
  • improving the performance monitoring
  • versioning
  • fetching more fields in the feed items, e.g. their thumbnails
  • using a streaming-friendly response format like JSON text sequences, jsonlines or ndjson
  • JSON Feed support
  • content-negotiation, e.g. letting clients specify the charset and format
  • support for other RPCs, e.g. GraphQL or JSON-RPC
  • support for other protocols, e.g. WebSocket
  • using the <ttl> RSS element for HTTP unconditional caching


RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free