Exposing aggregates through REST API

[Sergey Berezovskiy]

Hi,

I'm currently learning Microsoft Web API and trying to create REST API with this technology. But I'm stuck with aggregates in my domain. E.g. I have Order entity with collection of OrderItems. Should I treat only aggregate root as resource? I.e. 

POST /orders
GET  /orders/42

And pass back and forth whole order graph with order items. In this case client will be responsible for building whole graph before sending it. Or should I treat order items as separate resource:

POST /orders
GET  /orders/42
POST /orders/42/items
GET  /orders/42/items

In this case order will be created empty without any items. And client will post items to it later. Actually I see problem with this approach - we can have empty orders, if client will not add any items. So, how do you deal with aggregate objects when exposing them through REST API? And how do you check invariants of aggregate if you go with second approach? Thanks!

[Philip Nelson]

if you are posting json, having a resource type that contains your full aggregate makes perfect sense. There should be no direct tie to your underlying database structure anyway, so flatten, structure any way that makes sense to the caller

--
You received this message because you are subscribed to the Google Groups "API Craft" group.
To unsubscribe from this group and stop receiving emails from it, send an email to api-craft+...@googlegroups.com.
Visit this group at http://groups.google.com/group/api-craft.
For more options, visit https://groups.google.com/d/optout.

[Sergey Berezovskiy]

Thanks Philip. I know that first option makes sense. But it complicates client. He is responsible for building aggregate and checking invariants. Do you ever expose sub items of aggregate through API? How do you deal with invariants in that case?

[Kijana Woodard]

Your API and your aggregates are orthogonal constructs. They may align, but they may not.

There is an unfortunate tendency to make the web app nothing more than a database proxy.

---

From: Sergey Berezovskiy
Sent: ‎7/‎22/‎2014 1:41 AM
To: api-...@googlegroups.com
Subject: Re: [api-craft] Exposing aggregates through REST API

[Lars de Ridder]

Hi Sergey,

Both options can work in some form. In case of the first one, the client doesn't really have to check invariants, you can simply have him POST to see if his order is valid, right? You will just have to be careful in designing proper error responses so the client can act accordingly. You can also offer him a way of checking if the order is valid without having to POST, which means introducing another resource for this purpose, that the client can then GET to and get the same error response.

In case of the second, you basically offer the client a STORE resource, so one that he is responsible for. That can't be an order anymore however, as you don't know when it will be permanent and if you should actually process it. So it would then be better to model a basket resource, that the user can freely manipulate. You can then return validation errors if he tries to do something that is not allowed. When your client is done building his basket, he can POST to /baskets/42/order, which creates an order (and validates invariants again of course).

Hope that helps!

- Lars