How to make a REST endpoint in Base

A REST endpoint in Base is a method on a class, decorated to say what URL and HTTP method it answers, with the pieces of the request it needs pulled in as arguments. You write the logic; the decorators handle the wiring. This post walks the shape: declare a service, bind a method to a route, and pull the body, query, and path parameters you care about.

Turn it on

The router is one key in your settings. List the service classes that hold your routes:

export const WorkerSettings: BaseSettings = {
    name: 'my-worker',
    title: 'My Worker',
    version: '1.0.0',
    router: {
        services: [UserService],
    },
};

That is the wiring. Base reads the decorators on the listed services to learn the routes.

A service with routes

An HTTP service is a class marked as one, with methods bound to routes:

@HttpService()
export class UserService {
    @HttpRoute('GET', '/users/:id')
    async getUser(@HttpPath('id') id: string): Promise<User> {
        // ...
    }

    @HttpRoute('POST', '/users')
    async createUser(@HttpBody() body: CreateUser): Promise<User> {
        // ...
    }
}

@HttpRoute(method, path) binds a method to an HTTP method and a URL pattern. The method can be a single verb or a list of verbs. The path can carry parameters, like :id, which you then pull into the handler.

Pull what you need from the request

Rather than handing you a raw request to dig through, Base lets each handler declare the parts it wants as decorated parameters:

• @HttpPath('id') for a path parameter like the :id above.
• @HttpQuery('q') for a query-string value.
• @HttpBody() for the parsed request body.
• @HttpHeader('...') and @HttpCookie('...') for a header or a cookie.

Each handler asks for exactly the inputs it uses, and they arrive typed. A handler that needs the body and one query parameter declares those two and ignores the rest of the request. The request is not a bag you rummage through; it is a set of named inputs you request.

It composes with the rest of Base

Because the service is an injectable class, it gets its dependencies the same way everything else does: declare the repository or service you need, and Base provides it. Because the body can be a validated class, the data your handler receives has already passed its rules. Because the return value is serialized on the way out, you return an object and Base shapes the response. The route is the thin layer that names the URL; validation, injection, and serialization are the framework doing their jobs around it.

The mental model to keep

A REST endpoint is a decorated method on an @HttpService class: @HttpRoute says which URL and verb it answers, and parameter decorators pull in exactly the pieces of the request it needs, typed. List the service in your settings and Base wires the routes. It is the same two moves as everywhere in Base, applied to HTTP: add the router key, write one decorated class.