what is restcall,pathcall,namedcall in lagom.javadsl.api.Descriptor;

Question

I am new to microservices and Lagom framework, in the service api where we make ServiceCalls I do not understand the difference of namedcall, pathcall and restcall. where and when should we use which?

for instance in these calls:

  ServiceCall<NotUsed, Cargo, Done> register();
  restCall(Method.POST, "/api/registration", register()

  ServiceCall<NotUsed, NotUsed, Source<Cargo, ?>> getLiveRegistrations();
  pathCall("/api/registration/live", getLiveRegistrations())

  ServiceCall<User, NotUsed> createUser();
  namedCall("/api/users", this::createUser)

Answer 1

The Lagom Documentation covers it pretty well:

1. Named

The simplest type of identifier is a name, and by default, that name is set to be the same name as the name of the method on the interface that implements it. A custom name can also be supplied, by passing it to the namedCall method:

default Descriptor descriptor() {
    return named("hello").withCalls(
        namedCall("hello", this::sayHello)
    );
}

In this case, we’ve named it hello, instead of the default of sayHello. When implemented using REST, this will mean this call will have a path of /hello.

2. Path

The second type of identifier is a path based identifier. This uses a URI path and query string to route calls, and from it dynamic path parameters can optionally be extracted out. They can be configured using the pathCall method.

Dynamic path parameters are extracted from the path by declaring dynamic parts in the path. These are prefixed with a colon, for example, a path of /order/:id has a dynamic part called id. Lagom will extract this parameter from the path, and pass it to the service call method.

ServiceCall<NotUsed, Order> getOrder(long id);

default Descriptor descriptor() {
    return named("orders").withCalls(
        pathCall("/order/:id", this::getOrder)
    );
}

Multiple parameters can of course be extracted out, these will be passed to your service call method in the order they are extracted from the URL:

3. Rest Call

The final type of identifier is a REST identifier. REST identifiers are designed to be used when creating semantic REST APIs. They use both a path, as with the path based identifier, and a request method, to identify them. They can be configured using the restCall method:

ServiceCall<Item, NotUsed> addItem(long orderId);
ServiceCall<NotUsed, Item> getItem(long orderId, String itemId);
ServiceCall<NotUsed, NotUsed> deleteItem(long orderId, String itemId);

default Descriptor descriptor() {
return named("orders").withCalls(
        restCall(Method.POST,   "/order/:orderId/item",         this::addItem),
        restCall(Method.GET,    "/order/:orderId/item/:itemId", this::getItem),
        restCall(Method.DELETE, "/order/:orderId/item/:itemId", this::deleteItem)
);
}