Skip to main content

Versioning

The Http Plugin provides a versioning mechanism that allows you to manage different versions of your API endpoints. This is particularly useful when you need to introduce breaking changes or new features without affecting existing clients.

Enabling Versioning​

Configuration​

In order to enable versioning in your API, you need to configure the Http Plugin with the desired versioning strategy. The plugin supports 4 strategies for versioning: URI Versioning, Header Versioning, Media Type Versioning, and Custom Versioning. You can choose the strategy that best fits your needs. In order to enable versioning, you need to set the versioning property in the Http Plugin options to true. The versionOptions property accepts an object configuration.

export type VersionOptions = HeaderVersionOptions | MediaTypeVersionOptions | UriVersionOptions | CustomVersionOptions;

Configuring the versions available for your API​

In both, Controller and Method decorators, you can specify the versions available for your API endpoints. The @Controller decorator accepts a version property that defines the versions available for all methods in the controller. The @Method decorator accepts a version property that defines the versions available for that specific method. If a method does not have a version property, it will inherit the versions from the controller. If no versions are specified, the endpoint will be available for all versions.

Note: If you specify versions in both the controller and method decorators, the method versions will take precedence over the controller versions.

Also, you can specify a version as 'default' in the controller or method decorators. This will make the endpoint available for that version when no version is specified in the request or when it is specified but not recognized.

Here is an example of how to configure the versions available for your API endpoints:

versioning-example.ts
@Controller({
    path: 'users',
    version: ['v1', 'v2']
})
export class UserController {
    // All methods in this controller will be available for versions 'v1' and 'v2'
}

...

@Controller('users')
export class UserController {
    @Get({
        version: ['v1', 'v2']
    })
    getUser() {...}

    @Post({
        version: ['v2']
    })
    createUser() {...}

    @Post()
    createUserDefault() {...} // This method will be available for all versions since no versions are specified

    @Get({
        version: ['default']
    })
    getDefaultUser() {...} // This method will be available for the 'default' version
}

Versioning Strategies​

Here are an explanation of each versioning strategy and how it works

URI Versioning​

Is the most common versioning strategy, where the version number is included in the URL path. For example, /v1/users and /v2/users would represent two different versions of the same endpoint. When you enable URI versioning, the Http Plugin will automatically extract the version number from the URL path and route the request to the appropriate controller method based on the version.

http-plugin-options.ts
/**
 * Options for configuring the URI-based version resolver.
 */
export interface UriVersionOptions {
    type: VersionType.Uri;
    defaultVersion?: string;
}

Media Type Versioning​

Media Type Versioning is a versioning strategy where the version number is included in the Accept header of the request. For example, Accept: application/vnd.myapi.v1+json and Accept: application/vnd.myapi.v2+json would represent two different versions of the same endpoint. When you enable Media Type versioning, the Http Plugin will automatically extract the version number from the Accept header and route the request to the appropriate controller method based on the version.

http-plugin-options.ts
/**
 * Options for configuring the media type-based version resolver.
 */
export interface MediaTypeVersionOptions {
    type: VersionType.MediaType;
    key: string;
}

Header Versioning​

Header Versioning is a versioning strategy where the version number is included in a custom header of the request. For example, X-API-Version: 1 and X-API-Version: 2 would represent two different versions of the same endpoint. When you enable Header versioning, the Http Plugin will automatically extract the version number from the specified header and route the request to the appropriate controller method based on the version.

http-plugin-options.ts
/**
 * Options for configuring the header-based version resolver.
 */
export interface HeaderVersionOptions {
    type: VersionType.Header;
    header: string;
}

Custom Versioning​

Http Plugin also allows you to implement a custom versioning strategy by providing a custom resolver function. This function will receive the incoming request and should return the version number as a string. This allows you to implement any custom logic for determining the version of the request.

http-plugin-options.ts
/**
 * Options for configuring the custom version resolver.
 */
export interface CustomVersionOptions {
    type: VersionType.Custom;
    resolver: (req: HttpRequest) => string | undefined;
}