I'm working on an API whereby a specific call would replace a subtree of an XML document—rooted at some element—with another subtree.

The two options I'm considering for a response to this call are:

  • Return the DOM
  • Return the modified subtree

In the interests of developing a standardized, stable API, I'd like to get this right. Is there a best way to handle this type of scenario? What are the benefits and drawbacks of doing it one way over the other? Would it make sense to offer both these options to API consumers?

  • 1
    Hm, maybe my API should provide both two variants? – porton Jan 19 '12 at 17:03

There are three distinct parts.

  1. API Method 1: Locate a subtree, rooted at some element.

  2. API Method 2: Build a modified subtree and return it.

  3. API Method 3: Combine the first two API Methods into a composite API Method which locates and replaces a subtree with a modified tree.

You should offer all three.

  • It seems you haven't understood my question. I ask: Should (as the alternate to your three-steps algorithm) we just pass the DOM to the called function which would modify the subtree directly, using DOM, without explicitly building a subtree? – porton Jan 19 '12 at 18:02
  • It seems you haven't understood my answer. I modified it to emphasize that it's not a 3 step algorithm but three separate API methods to do Locate or Build or combine Locate and Build to be a Modify-in-Place. – S.Lott Jan 19 '12 at 19:39

Ideally, based on your description, the method shouldn't return anything.

The only reason you might want to return something is when you know for sure that it is a very common occurrence that callers need to use what you are returning right away. Look at it from the perspective of the caller. Do I need the entire DOM or just the updated branch? If you cannot easily decide, don't return anything.

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.