directus/docs/extensions/endpoints.md

description, readTime

description	readTime
A guide on how to build custom API endpoints in Directus.	3 min read

Custom API Endpoints

Custom API Endpoints register new API routes which can be used to infinitely extend the core functionality of the platform.

Extension Entrypoint

The entrypoint of your endpoint is the index file inside the src/ folder of your extension package. It exports a register function to register one or more custom routes. Each route of your endpoint will be a sub-route of /<extension-name>.

::: tip Extension Name

The extension name is usually the name of the folder where you put your extension when deploying it.

:::

Example of an entrypoint:

export default (router) => {
	router.get('/', (req, res) => res.send('Hello, World!'));
};

Alternatively, you can export a configuration object to be able to customize the root route:

export default {
	id: 'greet',
	handler: (router) => {
		router.get('/', (req, res) => res.send('Hello, World!'));
		router.get('/intro', (req, res) => res.send('Nice to meet you.'));
		router.get('/goodbye', (req, res) => res.send('Goodbye!'));
	},
};

The routes of this endpoint are accessible at /greet, /greet/intro and /greet/goodbye.

Available Options

• id — The unique key for this endpoint. Each route of your endpoint will be a sub-route of /<id>.
• handler — The endpoint's registration handler function.

Register Function

The register function receives the two parameters router and context. router is an Express router instance. context is an object with the following properties:

• services — All API internal services.
• database — Knex instance that is connected to the current database.
• getSchema — Async function that reads the full available schema for use in services
• env — Parsed environment variables.
• logger — Pino instance.
• emitter — Event emitter instance that can be used to trigger custom events for other extensions.

::: warning Event loop

When implementing custom events using the emitter make sure you never directly or indirectly emit the same event your hook is currently handling as that would result in an infinite loop!

:::

Example: Recipes

import { createError } from '@directus/errors';

const MyExtensionError = createError('MY_EXTENSION_ERROR', 'Something went wrong...', 500);

export default (router, { services }) => {
	const { ItemsService } = services;

	router.get('/', (req, res, next) => {
		const recipeService = new ItemsService('recipes', { schema: req.schema, accountability: req.accountability });

		recipeService
			.readByQuery({ sort: ['name'], fields: ['*'] })
			.then((results) => res.json(results))
			.catch((error) => {
				return next(new MyExtensionError());
			});
	});
};