"inline" inside collection VS inside item (= nested content ?)

[rastapopougros]

I found the inline-extension very interesting when some linked informations of an item are part of their own collections (and then have their URL in the API) : authors, categories, documents, GIS points, etc.

• For the moment, additional "inline" collections are only inside the "collection" object.
• I have carefully read in the initial discussion, that the first purpose is to preload, not to embed content.
• I have also read that "nested is messy".

But. :)

In my use, some informations are linked, but they are truly part of the item. And they are much more complex than just "data" name/value pairs (even with the "object" in value-types extension).

When "inline" is just in the "collection", it's ok when it's a resource URL, with only one item. We can retrieve all additional infos, and add them at the end. But it's normal because it's exactly like if "inline" were only for the item, in this case.

But when we are on a collection URL, even with pagination (imagine 100 items per page for ex) : this is both technically and semantically complicated to have those informations in one "inline" element in the collection, and not inside each relevant item.

I will describe few real world examples that I have encountered in my apps.

Example 1 : GIS points

I have different content types which have the possibility to have 0 to N geo points attached to each content. For ex, for my contents "artworks".

Each point have lat, lon, but also country, city, address… : this is in itself a content, with multiple fields/data.

Other linked infos like "artists", "tags", etc, could be only simple links with a human title, without any problem (href = API URL to the artist + title = his/her human name). It's ok.

But unlike those, geo points are part of the content. They define where the content (here artwork) is. For ex to place each content directly on a map, etc. Each point is like a field/data for this content, but more complex : so, yes : nested content. :)

And obviously we want those geo infos immediately for each item. With no additional HTTP request. :)

Example 2 : Documents with additional editorial content

It's something similar, but for another type of information.

I have 0 to N documents attached to contents. But documents are not just links to files, and not just with a title in addition. Here documents are editorial content : a file yes, but also a title, a description, some credits…

Example 3 : Routes with steps (and steps with docs)

Even more complex content.

I have a content type "routes".
=> Each route have simple field/data like title, description, difficulty, length, duration, etc.
=> But each route MAY have 0 to N "steps", and each step have its own simple data : title, description, geolocation…
=> Re-But each step MAY have 0 to N documents (cf previous)attached.

So there is a 3-depth content : route => step(s) => doc(s).

But my collection is a "route collection". When I get-request, I want all information about a route, in one request. I want all steps, and all docs of all steps, inside my route (because they are the content of the route).

Conclusion

With all of that, I don't see (for the moment) another solution that having inline collections inside each item.

Those examples are just one-item collection, so one resource, but it's obviously more important to have inside-item inline collections when we get a complete collection, with many items.

Resource of an artwork containing 2 geo points and 6 medias

{ "collection" :
  {
    "version" : "1.0",
    "href" : "http://example.org/api/artworks/",

    "items" : [
      {
        "href" : "http://example.org/api/artworks/123",
        "data" : [
          {"name" : "title", "value" : "Les Misérables", "prompt" : "Title"},
          {"name" : "description", "value" : "A book blablabla…", "prompt" : "Description"}
        ],
        "links": [
          { "rel": "author", "href": "http://example.org/api/authors/456"}
          { "rel": "gis", "href": "http://example.org/api/gis/?object=artwork&id_object=123", "length": 2, "inline":true },
          { "rel": "attachments", "href": "http://example.org/api/documents/?object=artwork&id_object=123", "length": 6, "inline":true },
        ],
        "inline": {
          "http://example.org/api/gis/?object=artwork&id_object=123": { /* embedded GIS collection attached to this artwork */ },
          "http://example.org/api/documents/?object=artwork&id_object=123": { /* embedded Documents collection attached to this artwork */ },
        }
      }
    ]
  }
}

Resource of a route containing steps (which contains docs)

{ "collection" :
  {
    "version" : "1.0",
    "href" : "http://example.org/api/routes/",

    "items" : [
      {
        "href" : "http://example.org/api/routes/123",
        "data" : [
          {"name" : "title", "value" : "A ride through the region", "prompt" : "Title"},
          {"name" : "length", "value" : "12km", "prompt" : "Length"}
          …
        ],
        "links": [
          { "rel": "steps", "href": "http://example.org/api/steps/?id_route=123", "length": 6, "inline":true },
        ],
        "inline": {
          "http://example.org/api/steps/?id_route=123": { "collection": {
            "items": [
              {
                "href": "http://example.org/api/steps/1",
                "data":[…title…description…],
                "links": [
                  { "rel": "attachments", "href": "http://example.org/api/documents/?object=step&id_object=1", "length": 5, "inline":true }
                ],
                "inline": {
                  "http://example.org/api/documents/?object=step&id_object=1": { /*Documents attached to this step*/ }
                }
              }
            ]
          }}
        }
      }
    ]
  }
}