Route

In this guide, we'll go through the steps to create a new route in your SoapJS project. You can create routes using CLI commands, interactive forms, or by defining them in a JSON file.

First, let's look at an example route implementation:

TypeScript

export class GetCustomerDetailsRoute {
  static create(handler: RouteHandler, config: Config) {
    return new GetCustomerDetailsRoute(
      'shop/customers/:id',
      handler,
      // additional options
      {
        io: new GetCustomerDetailsRouteIO(),
        auth: {
          authenticator: 'passport',
          type: 'jwt',
          secretOrKey: config.secret,
        },
        validation: {
          validator: 'ajv',
          schema: GetCustomerDetailsSchema
        },
        cors: {
          origin: '*',
        },
        throttler: {
          maxRequestsPerSecond: 1
        },
        limiter: {
          maxRequests: 1
        },
        middlewares: [SelfDataAccessMiddleware]
      }
    );
  }
}

This route class GetCustomerDetailsRoute is responsible for handling customer detail retrieval requests. The create method initializes the route with a specific URL pattern, handler function and additional options.

Creating new route

Using CLI Command with options

To create a new route directly via the CLI, use the following command:

soap new route -n "Customer" -e "shop" -h "getCustomerDetails(id:string):Entity<Customer>" -w -f

Options explained:

• -n: Name the route.

• -e: Endpoint associated with the route (e.g., "shop").

• -m: HTTP request method.

• -p: Route path.

• -c: Controller associated with the route (e.g., "customer").

• -h: Specify the controller method (handler) name.

• -a: Authentication method (e.g., jwt).

• -v: Include request validation

• -b: Specify the request body structure.

• -r: Specify the response body structure

• -l: Use rate limiter

• -t: Use throttler

• -s: Use CORS

• --no-tests: Skip test generation.

• --no-rel: Skip generating related files. You can also specify specific groups.

• --force: Force the creation, overwrite files if necessary.

• --patch: Add content to the files if they exists.

• --help: display help for command

Using Interactive Form

If you prefer to use an interactive form to specify your route details, simply run:

soap new route -w -f

Follow the prompts to enter your route's details.

Using JSON Configuration

Alternatively, you can define your route in a JSON file. Here is an example structure:

{
  "routes": [
    {
      "name": "GetCustomerDetails",
      "endpoint": "shop",
      "controller": "customer",
      "handler": "getCustomerDetails",
      "request": {
        "method": "GET",
        "path": "customers/:id",
        "validate": false,
        "auth": "none"
      },
      "response": {
        "200": "RouteModel<GetCustomerDetailsResponse>",
        "500": "string",
        "404": { "message": "string", "error_code": "number" }
      }
    }
  ]
}

Save this to a file, for example api.json, and run:

soap new --json "./path/to/api.json" -w -f

Options:

• --json: Path to your JSON configuration file.

• -w: Generate with dependencies included.

• -f: Force the creation, overwrite files if necessary.

File Structure

After creating your route, your file structure (assuming default configuration settings) should look like this:

src/
  - shop/
    - domain/
      - entities/
        - customer.ts
        - index.ts
      - controllers/
        - customer.controller.ts
        - index.ts
    - routes/
      - get-customer-details.route.ts
      - get-customer-details.route-io.ts
      - get-customer-details.route-model.ts
      - index.ts
  - router.ts
  - dependencies.ts
...

This structure will help you maintain a clean separation of concerns within your SoapJS application, promoting better organization and scalability.