@Get

Annotate methods with @Get for HTTP GET web routes.

@Controller
@Path("/customers")
class CustomerController {

  @Get
  List<Customer> getAll() {
    ...
  }

  @Get("/:id")
  Customer getById(long id) {
    ...
  }

  @Get("/:id/contacts")
  List<Contacts> getContacts(long id) {
    ...
  }

}

Path parameters

Path parameters have a : colon prefix (as they do with Javalin). For example: :id, :name, :startDate etc.

The path parameter names need to be matched by method parameter names on the controller. For example:

@Get("/:id/:startDate/:sort")
List<Bazz> findBazz(long id, LocalDate startDate, String sort) {

  // id, startDate, sort ... match
  ...
}

The design choice is that this convention means that we don't need a @PathParam annotation. When using JAX-RS @PathParam the annotation value almost always matched the method parameter and so this annotation is "noise" without additional value.

As such DInject Controllers do not have a @PathParam annotation and instead rely on the convention that the path parameter and method parameter names match.

The JAX-RS equivalent to the above would be:

// JAX-RS

@GET
@Path("/{id}/{startDate}/{sort}")
List<Bazz> findBazz(@PathParam("id") long id, @PathParam("startDate") LocalDate startDate, @PathParam("sort") String sort) {

  // we start getting "annotation noise" ...
  // making the code hard to read

}

Query parameters

Method parameters that don't match a path parameter are implicitly considered a query parameter.

In the following example orderBy is not a path parameter and defaults to being a @QueryParam

@Get("/:id/:date")
public List<Cat> findCats(long id, LocalDate date, String orderBy) {
  ...
}

We use @QueryParam when we want to be explicit or when a query parameter uses snake case or similar that isn't a valid Java/Kotlin identifier. For example:

In the following example we explicitly use @QueryParam("order-by") because of snake case parameter "order-by" is not a valid Java/Kotlin identifier.

@Get("/:id/:date")
public List<Cat> findCats(long id, LocalDate date, @QueryParam("order-by") String orderBy) {
  ...
}