90b59d89e0
* Rename API Endpoints docs to Endpoints to align with Hooks * Add a Creating Extensions page to the docs * Update individual extension docs pages * Apply latest changes to hook docs * Move available events to a dedicated section in hook docs
2.4 KiB
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',
register: (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>.register— The endpoint's register 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.exceptions— API exception objects that can be used to throw "proper" errors.database— Knex instance that is connected to the current database.getSchema— Async function that reads the full available schema for use in servicesenv— Parsed environment variables.logger— Pino instance.
Example: Recipes
export default (router, { services, exceptions }) => {
const { ItemsService } = services;
const { ServiceUnavailableException } = exceptions;
router.get('/', (req, res, next) => {
const recipeService = new ItemsService('recipes', { schema: req.schema, accountability: req.accountability });
recipeService
.readByQuery({ sort: [{ column: 'name', order: 'asc' }], fields: ['*'] })
.then((results) => res.json(results))
.catch((error) => {
return next(new ServiceUnavailableException(error.message));
});
});
};