Best practices for mapping RESTful resources to existing domains

Question

We are are going to be creating some RESTful services which are essentially going to be a passthrough to some ye-olde-fashioned SOAP-based webservices. The SOAP services are more generalized and will used across our entire organization (at least that's the plan). The RESTful services are tailored to specific clients. This decision was already made and is unfortunately out of my control to change...

We're struggling with how to structure our RESTful resources in a way that makes sense, follows REST best practices, and call these SOAP services without causing ourselves too much pain.

We have some freedom around the level of granularity for the back-end services, but the general consensus is: keep them coarse grained and don't tailor them to the specific client's needs.

This is leading to some interesting problems. For instance, how to deal with child resources of a parent. The typical example we've been working with is this: a customer with a child address.

We have a back-end SOAP service which updates a customer as a whole entity. However, the REST services client might need to update just the billing address. How do we best handle subsequent updates of the child resource?

Should we do the updates at the "parent" level (the customer), or expose a more fine-grained REST operation that treats the address as a resource and update it that way? The latter seems to be the correct, RESTful way. But, if we do that, we'll essentially be calling a coarse-grained backend service for just one piece of an update. Doesn't seem to make sense as it's a pretty heavyweight call.

We're also struggling a bit with how to correlate RESTful resources with our back-end domain model. We might care about the RESTful resource as a single entity but in our domain on the back-end, it might be many different entities. We've got a relatively simple DB table to handle this now, but I'm not convinced it will scale out as we map more and more resources to domain objects.

These are just a couple of examples of the things we're hitting... I'm wondering if anyone has run into similar issues and has any words of advice or might be able to point me to some articles that might have some best practices.

It seems like it this isn't an unusual problem and will become more relevant as more and more applications use RESTful architectures, but I can't seem to find any other info on it.

Thanks much!

Answer 1

I've found that most domains I model map very easily to REST. The most important thing to do is get into the right state of mind. REST models domains as a set of resources, where SOAP tends to emphasize a set of actions. Another way to look at this is that REST focuses on states and SOAP on state transitions. Even simpler you can think of REST as nouns versus SOAP as verbs. I know this isn't a perfect analogy but it's useful for me.

When you get into this state of mind the mapping should be almost automatic for you. Let's look at your Customer address interaction.

I don't think it's inappropriate to update the whole customer just to update the address, but not being familiar with your domain, maybe it is. If you want to specifically interact with the address just create a sub-resource (or nested resource). You end up with the following mapping of url's and verbs:

GET /customer/72/address    # return the address of customer with id 72
PUT /customer/72/address    # update the address of customer with id 72

In this particular case it probably doesn't make sense to map the delete, create or list actions.

If your customer has a collection of some entity, let's say widgets, you could map the interactions like this:

GET     /customer/72/widgets        # return the widgets of customer with id 72
POST    /customer/72/widgets        # create a new widget for customer with id 72
GET     /customer/72/widgets/158    # return widget with id 158 of customer 72
PUT     /customer/72/widgets/158    # update widget with id 158 of customer 72
DELETE  /customer/72/widgets/158    # delete widget with id 158 of customer 72

Just have the right mindset and keep in mind the mapping won't be one-to-one and you'll be fine.