As you may have already noticed, we created two situations in this code: one clearly coupled (getUserCoupled) and another decoupled (getUserDecoupled):

    public Response getUserCoupled(
            @PathParam("name") String name, 
            @PathParam("email") String email)

Why is this a coupled method and thus a coupled service? Because it is highly attached to the method signature. Imagine it is a search service and "name" and "email" are filters. Now imagine that sometime in the future you need to add another filter. One more parameter in the signature.

OK, you could keep the two methods alive at the same time, so that you wouldn't break the client and have to change the clients. How many are there? Mobile, services, web pages, and many more. All those need to be changed to support the new feature.

Now look at this:

    public Response getUserDecoupled(@HeaderParam("User") User user)

In this User search method, what if you need to add a new parameter to the filter? OK, go ahead and add it! No changes in the contract, all clients are happy.

If your User POJO starts with only two properties and ends with a hundred after a year, no problem. Your service contract is left untouched and even your clients, who are not using the new fields, are still working. Sweet!

The result of coupled/decoupled services can be seen in the calling service: 

    public Response doSomethingCoupled(String name, String email){
        WebTarget service = 
        target.path("webresources/userService/getUserCoupled");
        service.queryParam("name", name);
        service.queryParam("email", email);

        ...
    }

The calling service is totally coupled to the called one: it has to know the called service properties' names and needs to add/update each time it changes.

Now look at this:

    public Response doSomethingDecoupled(User user){
        WebTarget service = 
        target.path("webresources/userService/getUserDecoupled");

        Response response;
        try {
            response = service.request().header("User", 
            Entity.json(user)).get();
            ...
    }

In this case, you only need to refer to the one and only service parameter ("User") and it will never change, no matter how the User POJO is changed.