# 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:

{% tabs %}
{% tab title="TypeScript" %}

```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]
      }
    );
  }
}
```

{% endtab %}
{% endtabs %}

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:

```bash
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:

```bash
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:

```json
{
  "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:

```bash
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.soapjs.com/components/route.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.