8

In a major application REST API that covers several related domains, does it make more sense to split resources into 'areas' based on the business domain they belong to or is it better to to maintain a single model?

For example, there are 'Sales' and 'Inventory' sub-domains. Users of the system typically only care about one domain at a time, but exceptions are possible. There is an 'Item' concept that exists in both domains so we could implement the 'item' resource in two different ways.

  1. have different resources to represent the concept in each domain, each resource holding only the relevant data:

    /sales/items/:id

    /inventory/items/:id

  2. have a single resource with all the data to be used in all contexts:

    /items/:id

There are also plenty of resources that only belong to one of the domains.

pros of 'areas'

  • easier to understand the API for users who only care about a single domain
  • easier to implement resources (less stuff to read/update at a time)
  • resources can be more specialized/optimized for each particular domain
  • ability to control access to resources at more granular level

pros of a single unified model

  • no duplicated resources for concepts that belong to more than one domain
  • if a user needs to work with multiple domains, he will only have to use a single API that covers all his needs

Is API partitioning as described above a valid way to reduce complexity of both API contract and implementation? I haven't seen it mentioned much anywhere.

Are there any more things that need to be considered to make a decision in favor of either approach?

6

I think that this is the perfect fit for Bounded Context pattern from Domain Driven Design.

Large models don't scale well, it's better to split them into smaller models (bounded contexts) and explicitly declare their relationships (common entities, interactions between bounded contexts etc.)

In this case you would have two bounded contexts (sales and inventory) with one shared resource (item). Interpretation of item in sales context may be a bit different than in inventory context and that's completely fine.

To use this pattern, you should:

  • identify the boundaries of different contexts (which you partly did by creating subroots /sales/ and /inventory/)
  • identify shared resources (item) and explicitly describe what is resource's interpretation in different bounded contexts
  • identify interactions between bounded contexts (which is probably out of scope of this question)

Note on

pros of a single unified model: no duplicated resources for concepts that belong to more than one domain

From REST point of view, resource is not duplicated. One resource can be identified by multiple URIs, each can have different representations (fitting for given bounded context).

  • This approach does seem superior overall. Just want to be sure I'm not overlooking any benefits of the alternative. – astreltsov Apr 26 '15 at 17:35
0

I think the rule of thumb should be the following.

If an item itself is unthinkable without being related to sales or inventory, you should go for option 1.

If an item can exist without any relation to sales/inventory or this relation is not really strong in your architecture, you could go for option 2.

  • I made the example a bit more clear. The 'item' does exist in both domains, that's the problem. But there are also concepts that only exist in one of the domains. – astreltsov Apr 22 '15 at 15:41
  • @astr Well, in this case I vote for separation. – Vladislav Rastrusny Apr 23 '15 at 8:01

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.