Uploaded image for project: 'Spring Data REST'
  1. Spring Data REST
  2. DATAREST-221

Support use case-driven inlining of managed resources



    • Type: New Feature
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: None
    • Fix Version/s: 2.1 M1 (Dijkstra)
    • Component/s: None
    • Labels:
    • Sprint:
      44 - Codd GA, 45 - Dijkstra M1


      This is a high-level ticket to kick off a discussion regarding what I believe is an important need for the Spring Data REST framework.

      This is mostly autobiographical, just because I've had enough relevant experience over the past few years that I think/hope the perspective will be valuable.

      I've built three REST APIs for three different corporate clients over the past few years. The first one was a custom build (Spring Web MVC + Hibernate), but the second and third started out as Spring Data REST implementations (more on that in a bit). In each case, the API users explicitly considered and rejected what I'll call "one-deep" endpoint schemas of the sort that Spring Data REST produces. What I mean here is that the top-level resource includes its simple properties directly, but exposes its exported/managed associations as links, with no inlining option besides the heavyweight option of simply implementing custom endpoints.

      FWIW, I don't myself care for one-deep schemas, because they're driven more by the desire to keep the API framework simple (simple rules, simple implementation) than they are by the app-specific use cases. For example, when getting a single resource by ID, it's very common to want a deep view of the data, and it's a minor annoyance to have to make repeated calls to get associations that probably fall on the 80% side of the 80/20 rule. A more important case is where we want to load collection data. Here we really want to avoid the dilemma between n+1 queries on the one hand and a bunch of client-side stitching together of bulk query data on the other. With collection data we can often still identify associations that are probably desired with the original call, even if it's again an 80/20 judgment call.

      Anyway, in all three of the cases that I mentioned above the users expressed a lack of enthusiasm about the one-deep approach. They were a captive audience, so they would have had to suck it up if I said "that's just how the framework works." But I wanted to delight them, not tell them that they had to accept something that I myself rejected. The result for the second and third APIs I mentioned above was that I ended up abandoning SDR itself. I kept Spring Data Commons (e.g. PersistentEntity, Repositories and the various repo base interfaces), Spring Data JPA and Spring HATEOAS, but effectively rebuilt a subset of SDR (including CRUD controller, property controller, search controller, PersistentEntityResource, etc.) in such a way that I could control resource inlining on a per use case basis.

      While it's usually possible to come up with client workarounds (batch query stuff, cache it, assemble everything client side), that's often a tough sell, and ultimately the framework should help us build REST APIs that our users love rather than tolerate. There's nothing un-RESTful about resource inlining, so my suggestion is that SDR start exploring ways to move in this direction.

      I have ideas on the technical approach, but as this is already long enough, I'll give others the chance to weigh in on the basic concept before offering technical suggestions.


          Issue Links



              olivergierke Oliver Drotbohm
              ww4 Willie Wheeler
              Last updater:
              4 Vote for this issue
              15 Start watching this issue