In SOA architecture should single API do everything or API should be split as multiple action

Question

We have an app which is exposing a RESTful API to a UI for purchasing an item. I have a question regarding API design. Lets say the following action should be taken in order

1. Item to be chosen for purchase
2. Next give the address to be delivered to

My question is: should we design a single API which gets both data perform both? Or should we design two API calls - one that creates a purchase record and second that update the address to be delivered to?

Answer 1

The recommended SOA approach is to choose coarse-grained services, which would seem to argue the minimum amount of API calls.

However, from a business point of view, item selection and purchase and item delivery are two very different concerns that should be separate components in your architecture. For item selection, you need to consider things like inventory and pricing. For delivery address, you need to consider user address lists, address validation, shipping, and taxation.

Those two components are not likely to interact much except maybe some external association between an item id and address id. For this reason, I'd recommend two API calls. Functionally, this would also allow your API users do things like update the delivery address without re-purchasing an item, send the bill to one address and the item to another address, etc.

Answer 2

As you state that you design a RESTful API you usually start by designing resources instead of the intended calls. Later on, resource representations can be chosen that include other resources for optimised HTTP request counts.

You might want to choose to proceed the following way:

1. Model the item list resource (GET - lists all items, POST - allows item creation) /items/
2. Model the address list resource /addresses/
3. Model the item instance resource /items/item/resourceId
4. Model the address instance resource /addresses/address/resourceId

Now all of your resources are available you can think about usage patterns. All your resources are generically available and can be mashed up. Possible approaches to answer your questions would be:

1. Extend the item instance resource with the needed address details (coarse grained as lreeder stated)
2. Model a resource /deliverydetails/ as list and instance resource containing item(s) and address, make the deliverydetails to be queried by item id or whatever your use case fits best

Hope that helps! Btw. you are automatically following SOA approaches with a Resource Oriented Design. Interfaces will be naturally fitting your business requirements and generic enough to support more advanced use cases.

Here is a good example