{"id":15681084,"url":"https://github.com/lirantal/express-version-request","last_synced_at":"2025-07-17T22:34:28.394Z","repository":{"id":54766744,"uuid":"90030112","full_name":"lirantal/express-version-request","owner":"lirantal","description":"versions an incoming request to Express based on header or URL","archived":false,"fork":false,"pushed_at":"2021-01-30T17:52:13.000Z","size":456,"stargazers_count":11,"open_issues_count":2,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-09T09:44:13.864Z","etag":null,"topics":["api","api-versioning","express","middleware","nodejs"],"latest_commit_sha":null,"homepage":null,"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/lirantal.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}},"created_at":"2017-05-02T12:18:35.000Z","updated_at":"2021-12-13T15:36:44.000Z","dependencies_parsed_at":"2022-08-14T02:10:43.453Z","dependency_job_id":null,"html_url":"https://github.com/lirantal/express-version-request","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/lirantal/express-version-request","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lirantal%2Fexpress-version-request","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lirantal%2Fexpress-version-request/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lirantal%2Fexpress-version-request/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lirantal%2Fexpress-version-request/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lirantal","download_url":"https://codeload.github.com/lirantal/express-version-request/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lirantal%2Fexpress-version-request/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265292908,"owners_count":23742181,"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":["api","api-versioning","express","middleware","nodejs"],"created_at":"2024-10-03T16:49:13.792Z","updated_at":"2025-07-17T22:34:28.367Z","avatar_url":"https://github.com/lirantal.png","language":"JavaScript","readme":"# express-version-request\n\n\n[![view on npm](http://img.shields.io/npm/v/express-version-request.svg)](https://www.npmjs.org/package/express-version-request)\n[![view on npm](http://img.shields.io/npm/l/express-version-request.svg)](https://www.npmjs.org/package/express-version-request)\n[![npm module downloads](http://img.shields.io/npm/dt/express-version-request.svg)](https://www.npmjs.org/package/express-version-request)\n[![Build Status](https://travis-ci.org/lirantal/express-version-request.svg?branch=master)](https://travis-ci.org/lirantal/express-version-request)\n[![codecov](https://codecov.io/gh/lirantal/express-version-request/branch/master/graph/badge.svg)](https://codecov.io/gh/lirantal/express-version-request)\n[![Security Responsible Disclosure](https://img.shields.io/badge/Security-Responsible%20Disclosure-yellow.svg)](https://github.com/nodejs/security-wg/blob/master/processes/responsible_disclosure_template.md)\n\n[![express-version-request](https://snyk.io/advisor/npm-package/express-version-request/badge.svg)](https://snyk.io/advisor/npm-package/express-version-request)\n\n## What is this?\n\nThis npm package provides an ExpressJS middleware that sets the request object with a `version` property by parsing a request HTTP header.  \n\n## Usage\n\n### Set request version statically\n\nIf you wish to employ your own logic in some middleware/configuration and set the request version programmaticaly and not by parsing a specific HTTP header:\n\n```js\nconst versionRequest = require('express-version-request')\n\napp.use(versionRequest.setVersion('1.2.3'))\n```\n\nThen in later middlewares you will be able to access `req.version` property and it's value set to 1.2.3.\n\n### Set request version by HTTP header\n\nBy default, the library will parse the version out of the `X-Api-Version` HTTP header:\n\n```js\nconst versionRequest = require('express-version-request')\n\napp.use(versionRequest.setVersionByHeader())\n```\n\n### Set request version by custom HTTP header\n\nIf you wish to advise the library which HTTP header to parse to extract the version:\n\n```js\nconst versionRequest = require('express-version-request')\n\napp.use(versionRequest.setVersionByHeader('My-HTTP-Header-Name'))\n```\n\n### Set request version by HTTP query parameter\n\nBy default, the library will parse the version out of the `api-version` query parameter:\n\n```js\nconst versionRequest = require('express-version-request')\n\napp.use(versionRequest.setVersionByQueryParam())\n```\n\n### Set request version by custom HTTP query parameter\n\nIf you wish to advise the library which query parameter to parse to extract the version:\n\n```js\nconst versionRequest = require('express-version-request')\n\napp.use(versionRequest.setVersionByQueryParam('myQueryParam'))\n```\n#### setVersionByQueryParam options \nThe second parameter of `setVersionByQueryParam` is an options object.\n\n### Set request version by 'Accept' header\n\nBy default, the library will parse the version from the Accept header, expecting the following format:\n**Accept: application/vnd.company+json;version=1.0.0**\nFor more details about the Accept header format, please refer to the [RFC](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html).\n\n\n```js\nconst versionRequest = require('express-version-request')\n\napp.use(versionRequest.setVersionByAcceptHeader())\n```\n#### Parsing using an alternative format\nAs a fallback, the lib supports an alternative Accept header format:\n\n**Accept: application/vnd.comapny-v1.0.0+json**\n\nor\n\n**Accept: application/vnd.comapny.v1.0.0+json**\n\nThe lib will try to parse the header using the default format, and if it doesn't succeed, tries this alternative format.\nThe usage is the same as in the case of the regular format:\n\n```js\nconst versionRequest = require('express-version-request')\n\napp.use(versionRequest.setVersionByAcceptHeader())\n```\n#### Parsing using a custom function\nIf you wish to use your own parsing, it is possible to pass a function as the first parameter.\nThe lib will then call it with the actual value of the Accept header as the first parameter, and the returned value will be set as version.\nThe provided function should return a **string**.\n\n```js\nconst versionRequest = require('express-version-request')\nfunction customParsingFunction(header) {\n\t//function body, that parses the header parameter and returns a string\n}\n\napp.use(versionRequest.setVersionByAcceptHeader(customParsingFunction))\n```\n#### Version formatting\nBefore setting the version, it is always formatted, so the resulting version is a semver comaptible string, except the following cases:\n\n* if the version was set as an Object, it will be returned in stringified format (using JSON.stringify)\n* if the version is longer than the semver format, we truncate it by cutting off the tail, and leaving the first three segments (e.g.: 1.2.3.4.5 will become 1.2.3)\n* if we encunter something, that can't be parsed or formatted as a version, undefined is returned\n\nThis formatting function is called automatically for each version setting method, but it can also be used independently:\n```js\nconst versionRequest = require('express-version-request')\nconst formattedVersion = versionRequest.formatVersion(versionThatNeedsFormatting)\n```\n##### Options\n\n`removeQueryParam`\n\nDelete version HTTP query parameter after setting the request object with a `version` property.\nBy default it is set to false.\n\n```js\nconst versionRequest = require('express-version-request')\nconst options = {removeQueryParam: true}\n\napp.use(versionRequest.setVersionByQueryParam('myQueryParam', options))\n```\n\nIf you define a middleware after versionRequest then you can verify that the version is indeed set:\n\n```js\napp.use((req, res, next) =\u003e {\n    console.log(req.version)\n    next()\n  })\n```\n\n## Installation\n\n```bash\nyarn add express-version-request\n```\n\n## TypeScript Support\n\n```bash\nyarn add --dev @types/express-version-request\n```\n\n_Note: Don't forget to add types for Express!_\n\n## Tests\n\n```bash\nyarn test\n```\n\nProject linting:\n\n```bash\nyarn lint\n```\n\n## Coverage\n\n```bash\nyarn test:coverage\n```\n\n## Commit\n\nThe project uses the commitizen tool for standardizing changelog style commit\nmessages so you should follow it as so:\n\n```bash\ngit add .           # add files to staging\nyarn commit      # use the wizard for the commit message\n```\n\n## Author\n\nLiran Tal \u003cliran.tal@gmail.com\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flirantal%2Fexpress-version-request","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flirantal%2Fexpress-version-request","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flirantal%2Fexpress-version-request/lists"}