@Path Decorator

@Path Decorator

The @Path decorator allow us to define a router path for a given endpoint. Route paths, in combination with a request method, define the endpoints at which requests can be made. Route paths can be strings, string patterns, or regular expressions.

The characters ?, +, *, and () are subsets of their regular expression counterparts. The hyphen (-) and the dot (.) are interpreted literally by string-based paths.

We use path-to-regexp for matching the route paths; see the path-to-regexp documentation for all the possibilities in defining route paths.

Some examples:

@Path("/hello")
class HelloService {
}

@Path("/test/hello")
class TestService {
}

This route path will match acd and abcd:

@Path("ab?cd")
class TestService {
}

This route path will match abcd, abbcd, abbbcd, and so on:

@Path("ab+cd")
class TestService {
}

This route path will match abcd, abxcd, abRANDOMcd, ab123cd, and so on:

@Path("ab*cd")
class TestService {
}

This route path will match /abe and /abcde:

@Path("/ab(cd)?e")
class TestService {
}

This route path will match butterfly and dragonfly, but not butterflyman, dragonfly man, and so on:

@Path("/.*fly$/")
class TestService {
}

Path Parameters

Route parameters are named URL segments that are used to capture the values specified at their position in the URL. The captured values are populated in the req.params object, with the name of the route parameter specified in the path as their respective keys. They can be referred through @PathParam decorator on a service method argument.

Some examples:

@Path("/users")
class UserService {
   @Path("/:userId/books/:bookId")
   @GET
   getUserBook(@PathParam("userId") userId: number, @PathParam("bookId") bookId: number): Promise<Book> {
      //...
   }
}

The requested URL http://localhost:3000/users/34/books/8989 would map the parameters as:

   userId: "34"
   bookId: "8989"

Since the hyphen (-) and the dot (.) are interpreted literally, they can be used along with route parameters for useful purposes.

Route path: /flights/:from-:to
Request URL: http://localhost:3000/flights/LAX-SFO
req.params: { "from": "LAX", "to": "SFO" }

Route path: /plantae/:genus.:species
Request URL: http://localhost:3000/plantae/Prunus.persica
req.params: { "genus": "Prunus", "species": "persica" }