Name embedded collections

[drdamour]

The Resources type (and any derived types, ie PagedResource) should allow you to name the collection that will eventually be the embedded set. It's auto named now, but the api developer should really have control over this.

[odrotbohm]

Can you elaborate what you mean by that? What exactly are you referring to with "name of the collection"? Relation names are abstracted away by a RelProvider and we ship two implementations: one based on the Evo Inflector library and one that creates a default …List for collection relations and uses the lower case simple class name for the item relations.

You're free to simply implement a RelProvider on your own, implement supports(Class<?> type) to select the types you want to be responsible for and register your implementation as Spring bean. This will cause the rendering infrastructure (e.g. the custom Jackson renderers we deploy) to call your implementation when calculating the relation names for representations.

[drdamour]

That can work as a workaround...but it is possible that i would have two collections of the same type with different semantic meaning.

So in the HAL format i could have something like this at /customer/123

{
  _links : [
    "favorite products" : [
         {href : "/products/998"},
         {href : "/products/777"}
    ],
    "purchased products" : [
         {href : "/products/998"},
         {href : "/products/444"},
         {href : "/products/333"},
         {href : "/products/222"},
         {href : "/products/111"},
         {href : "/products/555"},
         {href : "/products/666"},
     ]
 ]
}

but in my protocol i might implement something like the zoom protocol to get things embedded. so a url like /customer/123?expand=purchased products&size=4 should give back something like this:

{
  _links : [
    "favorite products" : [
         {href : "/products/998"},
         {href : "/products/777"}
    ],
    "purchased products" : [
         {href : "/products/998"},
         {href : "/products/444"},
         {href : "/products/333"},
         {href : "/products/222"},
         {href : "/products/111"},
         {href : "/products/555"},
         {href : "/products/666"},
     ]
 ],
_embedded : [
  {
    "purchased products" [
      {
        _links : { self : { href : "/products/998"} },
        someProductProperty : "someValue"
      },
      {
        _links : { self : { href : "/products/444"} },
        someProductProperty : "someValue"
      },
      {
        _links : { self : { href : "/products/333"} },
        someProductProperty : "someValue"
      },
      {
        _links : { self : { href : "/products/222"} },
        someProductProperty : "someValue"
      }
    ]
  }
],
page : { ...}
}

the embedded name should be the same as the link. So yes i could do this for one of the links, but the other at URL /customer/123?expand=favorite products&size=4 would be out of luck. and you could technically do both simultaniously (but paging both would be pretty strange).

Personally i want to just name the embedded paged collection items or page items as someTypeNameList isn't semantically meaningful enough. Your workaround will probably get me there.

[fiddlerpianist]

Traverson (the JS variety) attempts to perform this optimization (look for link relation name in _embedded if it's provided). The auto-generated name does not match what would be generated in a link list, and so Traverson can't find _embedded links.

[williewheeler]

+1 to drdamour's remarks, including the inadequacy of driving the name via types alone.

It would be useful for example to be able to do something like

PagedResources<PersonResource> pagedResources =
    new PagedResources("employees", employeeDtos, pageMetadata, links);

and have that show up as

"_embedded": {
    "employees": [ ... ]
}

rather than

"_embedded": {
    "personResourceList": [ ... ]
}

[gjrwebber]

+1

[marvinrichter]

For those who didn't get Olivers answer straight away, like me:

If you want the plural form of the class' name rather than uncapitalized class.getSimpleName + "List", you just need to use the EvoInflectorRelProvider instead of the standard DefaultRelProvider.

If you use Spring Boot, just add the following dependency

<dependency>
    <groupId>org.atteo</groupId>
    <artifactId>evo-inflector</artifactId>
    <version>1.2</version>
</dependency>

otherwise you need to also add the following bean to your configuration class

@Bean
public RelProvider relProvider() {
    return new EvoInflectorRelProvider();
}

These results in returning

"_embedded": {
    "users": [{
        "name": "Marvin"
    }]
}

instead of

"_embedded": {
    "userList": [{
        "name": "Marvin"
    }]
}

[odrotbohm]

As documented in the reference documentation. 😄

[marvinrichter]

lol. I totally missed the point 3. 😄

[zhengl7]

+1.

Also add to OP's comment, what's the rationale to have PagedResources returned under _embedded with class name? Is it possible to return just the array of data like non-HAL format?

Like for /v1/users/ just return

"_embedded": 
[
  {
    "name": "Marvin"
  },
  {
    "name": "Alex"
  }
]

This way client doesn't have to know the property name to look for under _embedded.

[odrotbohm]

The HAL specification.

[stephaneeybert]

Even if we can have, for example the name 'users' instead of the name 'userResourceList', we still have a name varying for each resource type. It'd be helpful to configure a static name, common to all resource types, like 'items' for example.

[marvinrichter]

@stephaneeybert having one static name for all collections would be very easy with the solution that @olivergierke suggested first.

Implement your custom RelProvider which will always return items for the collection name and itemfor the item name and always returns true for the method supports(Class<?> type). You can check out the DefaultRelProvider.

To be honest, I would not do that because the client is supposed to know what it was asking for anyway. And a resource type reflects a resource which itself should be identifiable and recognizable. Having everything named items sounds like the complete opposite of that.