weffe/axios-api-versioning

:diamond_shape_with_a_dot_inside: Add easy to manage api versioning to Axios

axios-api-versioning

Add easy to manage api versioning to axios

Online Demo

Visit Online Demo

Quick Start

Install

npm

npm install --save axios-api-versioning

yarn

yarn add axios-api-versioning

Example Usage

import axios from 'axios';
import { withVersioning, VersioningStrategy } from 'axios-api-versioning';

// create an axios instance with versioning
// and versioning config
const client = withVersioning(axios, {
    apiVersion: '1.0.0',
    versioningStrategy: VersioningStrategy.QueryString
});

client.get('http://example.com', {
    // override default apiVersion
    apiVersion: '2.0.2',
    // override default versioningStrategy
    versioningStrategy: VersioningStrategy.MediaType
})

TypeScript Support

TypeScript is supported! There's no need to install types for this package from the @types repository as they are provided by this package directly.

Documentation

You can visit the online docs here: https://weffe.github.io/axios-api-versioning

Example Projects

There are 2 example projects showcasing the usage of axios-api-versioning. You can check them out here:

1. with-nodejs
2. with-react-typescript

Changelog

You can view the changelog here.

Related Projects

• https://github.com/Microsoft/aspnet-api-versioning

License

MIT

axios-api-versioning's Issues

Add TravisCI for unit tests

I think it's a good idea to add CI for this project.

I still need to figure out the integration tests using axios-mock-adapter. But the other unit tests should work just fine.

Axios 1.0.0

This isn't an issue but more so a reminder for my sake and for documentation purposes.

There has been a PR merged into the 1.0.0 release branch for axios that address my concerns for issue #5 and would let us drop the need for custom axios types like AxiosResponseWithVersioning. It would also alleviate the need for me to keep the types in sync with the axios repo which is a nice benefit.

I have no idea when 1.0.0 version will be released but if it gets released and I haven't updated this project yet then feel free to ping me.

Have a good day! 🙂

Generic is not passed in type `AxiosRequestConfigWithVersioning`

Found a problem that the type AxiosRequestConfigWithVersioning does not pass a generic to AxiosResponse because of this, the return type is any

  export interface AxiosRequestConfigWithVersioning<T = any> extends AxiosResponse<T> {
                                                                                 __^
    config: AxiosRequestConfigWithVersioning;
  }

An in-range update of axios is breaking the build 🚨

The devDependency axios was updated from 0.19.0 to 0.19.1.

🚨 View failing branch.

This version is covered by your current version range and after updating it in your project the build failed.

axios is a devDependency of this project. It might not break your production code or affect downstream projects, but probably breaks your build or test tools, which may prevent deploying or publishing.

Status Details

• ❌ ci/circleci: build: Your tests failed on CircleCI (Details).

---

Commits

The new version differs by 47 commits.

• 960e1c8 Releasing 0.19.1
• 8a9421d Fixing typo in CHANGELOG.md: s/Functionallity/Functionality (#2639)
• ee47120 If this place is false, it will report an error, so you should delete the useless code. (#2458)
• 03e6f4b Fixing invalid agent issue (#1904)
• dc4bc49 fix: fix ignore set withCredentials false (#2582)
• 13c948e Remove 'includes' API, fix CI build failure (#2574)
• fa6cf01 fixing Travis link (#2540)
• a17c70c Fix CI build failure (#2570)
• 1a32ca0 Remove dependency on is-buffer (#1816)
• 0cc22c2 Fix badge, use master branch (#2538)
• 8414664 Fix XSS logic that matched some valid urls (#2529)
• bbfd5b1 Adding options typings (#2341)
• 55aaebc Document fix (#2514)
• 86d7750 Update docs with no_proxy change, issue #2484 (#2513)
• b0afbed Adding Typescript HTTP method definition for LINK and UNLINK. (#2444)

There are 47 commits in total.

See the full diff

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

Add ability to provide custom key name for media type and query string

Currently, the key names used for both Media Type and Query String are hardcoded as v and api-version respectively. It would be ideal to pass the key name in as a config option to withVersioning().

e.g.

For Media Type:

withVersioning(axios, {
  apiVersion: '2',
  versioningStrategy: VersioningStrategy.MediaType
  versionKeyName: 'my-custom-api-version' 
})

For Query String:

withVersioning(axios, {
  apiVersion: '2',
  versioningStrategy: VersioningStrategy.QueryString
  versionKeyName: 'my-custom-api-version' 
})

Maybe keyName can be ignored when the VersioningStrategy is UrlPath.

Something like this: https://codesandbox.io/s/k3j6p446kr?fontsize=14&view=editor

Possibly support custom media types?

Reference: https://github.com/Microsoft/aspnet-api-versioning/wiki/Versioning-by-Media-Type#custom-media-types

Should we support custom media types?

Currently, the mediaTypeKeyName and apiVersion is just appended to the Accept Header. The only way I can see this as a possibility is by providing a hook like mediaTypeFormatter(acceptHeader: string): string. If a user provides their own mediaTypeFormatter then we would use that instead of setting it ourselves like in the current way.

Find another way to expose apiVersion and versioningStrategy inside AxiosRequestConfig

Currently, we are modifying the global AxiosRequestConfig to add in apiVersion and versioningStrategy as optional properties. This is needed so TypeScript users can pass in those options on a request without getting any issues.

It would be better to find a different way to provide the same type safety without modifying the global AxiosRequestConfig.

What I can think of is creating our own type AxiosRequestConfigWithVersioning and exposing it. Then, recreate the axios interface with get, post, etc, to accept the AxiosRequestConfigWithVersioning instead of AxiosRequestConfig.

This also tightens things up in terms of type safety because as soon as you import this module then it automatically modifies AxiosRequestConfig. If a TypeScript user creates an axios instance that does not have versioning, they will still get the option to define apiVersion and versioningStrategy in the AxiosRequestConfig which could be confusing.

Reference:

axios-api-versioning/src/types.ts

Lines 37 to 46 in f680e77

	/**
	* modify the global axios type of AxiosRequestConfig
	* to add "apiVersion" & "versioningStrategy" to config object
	*/
	declare module "axios" {
	interface AxiosRequestConfig {
	apiVersion?: string;
	versioningStrategy?: string
	}
	}

Feedback Wanted

For the next version, I am in the process of trying to clean up the build process for this project. I would also like to clean up the way the custom Axios types (e.g. AxiosRequestConfigWithVersioning) are exported since I feel like the current way is a bit cumbersome.

Instead of:

import { AxiosRequestConfigWithVersioning } from 'axios-api-versioning/dist/types/axios';

I would rather prefer:

import { AxiosRequestConfigWithVersioning } from 'axios-api-versioning';

I would like some feedback from those that use this library if this TypeScript change is a good Quality of Life change.

Add project examples

It would be great to add project examples for usage on both the browser and on nodejs apps.

• browser example - learn more here
• nodejs example - learn more here