Add a REST endpoint

REST-style endpoints can be defined as part of a plugin.

Info

REST endpoints are implemented as NestJS Controllers. For comprehensive documentation, see the NestJS controllers documentation.

In this guide we will define a plugin that adds a single REST endpoint at http://localhost:3000/products which returns a list of all products.

Create a controller

First let's define the controller:

src/plugins/rest-plugin/api/products.controller.ts

// products.controller.tsimport { Controller, Get } from '@nestjs/common';import { Ctx, ProductService, RequestContext } from '@vendure/core';@Controller('products')export class ProductsController {    constructor(private productService: ProductService) {    }    @Get()    findAll(@Ctx() ctx: RequestContext) {        return this.productService.findAll(ctx);    }}

The key points to note here are:

The @Controller() decorator defines the base path for all endpoints defined in this controller. In this case, all endpoints will be prefixed with /products.
The @Get() decorator defines a GET endpoint at the base path. The method name findAll is arbitrary.
The @Ctx() decorator injects the RequestContext which is required for all service methods.

Register the controller with the plugin

src/plugins/rest-plugin/rest.plugin.ts

import { PluginCommonModule, VendurePlugin } from '@vendure/core';import { ProductsController } from './api/products.controller';@VendurePlugin({  imports: [PluginCommonModule],  controllers: [ProductsController],})export class RestPlugin {}

Info

Note: The PluginCommonModule should be imported to gain access to Vendure core providers - in this case it is required in order to be able to inject ProductService into our controller.

The plugin can then be added to the VendureConfig:

src/vendure-config.ts

import { VendureConfig } from '@vendure/core';import { RestPlugin } from './plugins/rest-plugin/rest.plugin';export const config: VendureConfig = {    // ...    plugins: [        // ...        RestPlugin, // [!code highlight]    ],};

Controlling access to REST endpoints

You can use the @Allow() decorator to declare the permissions required to access a REST endpoint:

src/plugins/rest-plugin/api/products.controller.ts

import { Controller, Get } from '@nestjs/common';import { Allow, Permission, Ctx, ProductService, RequestContext } from '@vendure/core';@Controller('products')export class ProductsController {    constructor(private productService: ProductService) {}    @Allow(Permission.ReadProduct) // [!code highlight]    @Get()    findAll(@Ctx() ctx: RequestContext) {        return this.productService.findAll(ctx);    }}

Tip

The following Vendure API decorators can also be used with NestJS controllers: @Allow(), @Transaction(), @Ctx().

Additionally, NestJS supports a number of other REST decorators detailed in the NestJS controllers guide