Improve self-descriptiveness of the search links [DATAREST-31] about spring-data-rest HOT 2 CLOSED

Oliver Drotbohm commented

Implementing this would also improve the discoverability of a paginated collection resource. Currently you get back the pagination information but not what parameters you need to provide to start pagination. With the metadata in place we could have something like this:

{ …
  "links" : [ {
    "rel" : "customer.search",
    "href" : "http://localhost:8080/customer/search"
  }, {
    "rel" : "self",
    "href" : "http://localhost:8080/customer",
    "params" : [
      { "name" : "page.number", "type" : [ "long" ], "optional" : true, "default" : 1 },
      { "name" : "page.size", "type" : [ "long" ], "optional" : true, "default" : 20 },
    ]
  }
}

Interesting aspect here is if we want to make optional parameters explicit or even expose default values as documented above

from spring-data-rest.

Oliver Drotbohm commented

We decided to take a slightly different route as adding too much meta information to the actual resources is suboptimal. Mostly because the meta information and the actual representation have very different lifecycles, especially in terms of caching. If we co-locate the meta information with the resource representation, we waste quite a bit of band width. This might not be an issue with the search resource as it shouldn't be requested too often but the approach effectively sneaks into all resources taking parameters of some sort.

We now discover the method parameters and create return a RFC6570 compatible URI template for all resources taking parameters. This semantic method parameters for query methods as well as the pagination parameters for query methods and the collection resources in general.

The semantics of the parameter names can then be documented through separate resources. While this might be a plain HTML page in the first place, we look into support for ALPS as a description format and automatically expose the information we already have as an ALPS resource. Follow DATAREST-230 if you're interested in that

from spring-data-rest.