ESX-RS

A library inspired by JAX-RS, allowing the description of REST endpoints through simple TypeScript decorators.

It has currently been integrated with:

| Integration | Type | Description | |:--------------------------------------------------------------------------|:-----------|:-----------------------------------------------------------------------------------------------------------| | esx-rs-client | Client | Proxy generator to access remote ESX-RS endpoints through a class instance. | | esx-rs-client-angular | Client | esx-rs-client network transport based on Angular HttpClient. | | esx-rs-client-fetch | Client | esx-rs-client network transport based on Fetch. | | esx-rs-client-http | Client | esx-rs-client network transport based on Node http. | | esx-rs-client-xhr | Client | esx-rs-client network transport based on XMLHttpRequest. | | esx-rs-server | Server | Dispatch incoming HTTP requests to ESX-RS decorated class methods. | | esx-rs-router-express | Server | esx-rs-server-based router middleware for Express. | | esx-rs-router-koa | Server | esx-rs-server-based router middleware for Koa. | | esx-rs-validation | Validation | Validation layer based on es-validation. | | esx-rs-schema-openapi | Schema | Schema generation for OpenAPI 3.0. |

Getting Started

The library can be installed using npm:

npm install esx-rs --save

Or using yarn:

yarn add esx-rs

Endpoints can then be described using decorators:

@Path('/users')
@Produces('application/json')
@Consumes('application/json')
class UsersEndpoint {

    @POST
    async createUser(user: User): Promise<User> {
        // ...
    }

    @PUT @Path('/:userId')
    async updateUser(@PathParam('userId') userId: string, user: User): Promise<User> {
        // ...
    }

    @GET @Path('/:userId')
    async getUser(@PathParam('userId') userId: string): Promise<User> {
        // ...
    }

    @DELETE @Path('/:userId')
    async deleteUser(@PathParam('userId') userId: string): Promise<void> {
        // ...
    }

}

Usage

Various decorators are available, each targetting a subset of the typical REST properties for a service.

Method

The HTTP method(s) can be specified using:

• @DELETE
• @GET
• @HEAD
• @OPTIONS
• @PATCH
• @POST
• @PUT
• @HttpMethod

Path

The resource path can be specified using:

• @Path

Note: the path-to-regexp format is used, e.g. /path/to/:resourceId/subpath/:subresourceId.

Resource Type

The type of resource, either consumed by the operation (mapped to content-type) or produced by the operation (mapped to accept), can be specified using:

• @Consumes
• @Produces

Multiple media types may be specified.

Parameters

Operation parameters and resource properties are mapped using a specific decorator for each parameter type:

• @CookieParam
• @FormParam
• @HeaderParam
• @MatrixParam
• @QueryParam
• @PathParam

Context

It is also possible to map the following context information to a parameter using the @ContextParam decorator:

• HttpContext
• HttpRequest
• HttpResponse

Endpoint vs. Operation

Many decorators can be applied to both a class and its methods.

In this scenario, the OperationInfo object returned for a method contains merged information that includes both the operation and the endpoint information.

The following decorators can be applied to both classes and methods:

• @DELETE, @GET, @HEAD, @OPTIONS, @PATCH, @POST and @PUT
• @Consumes and @Produces
• @Path

The @Path decorator is handled a bit differently: the operation path is appended to the endpoint path.

Limitations

At the moment, only concrete classes can be decorated.

This is due to the way ECMAScript gets generated, as interfaces no longer exist in the generated code.