-1

We are building a backend RESTful service for a workflow builder. The service's responsibilities will be to accept workflow definitions from a frontend and store them in a database.

We are trying to decide between the following two choices for the structure of the API.

Choice 1: Single API, saveWorkflowDefinition, which takes the entire definition from the frontend as a json and dumps it into the db after validating the json.

Pros:

  1. Simpler API implementation, lesser dev effort.

Cons:

  1. Every API call will send the entire workflow definition which will result in high network bandwidth usage.
  2. Complex computation for workflow definition validation. Input structure will be too complex.

Choice 2: Multiple smaller APIs, like addWorkflowNode, removeWorkflowNode, updateNodeDefinition.

Pros:

  1. Smaller API calls will result in optimal network bandwidth usage.

  2. Easier to do input validation. Simpler api signatures

Given the above pros/cons and given that dev effort is not a major deciding factor, we are planning to go ahead with Choice 2. Are there any other pros/cons that we are missing for both the approaches?

Sarthak Jain
  • 121
  • Sharing your research helps everyone. Tell us what you've tried and why it didn't meet your needs. This demonstrates that you've taken the time to try to help yourself, it saves us from reiterating obvious answers, and most of all it helps you get a more specific and relevant answer. Also see [ask] – gnat Oct 13 '19 at 17:16
  • Please read "Why questions about 'the correct way' are too broad." – Robert Harvey Oct 13 '19 at 22:09
  • Edited the question to list some pros/cons of both approaches. Need to know if we are missing some important pros/cons? – Sarthak Jain Oct 14 '19 at 05:36
  • Thanks for adding the pros and cons. You may want to look at this related question for a different set of pros/cons around performance and reliability. (The context in that question is a little different - multiple records in a store vs. nodes in workflow - but the idea is similar.) https://softwareengineering.stackexchange.com/questions/134220/sending-a-collection-of-data-to-an-api-multiple-small-calls-vs-one-big-call – Anton Oct 15 '19 at 03:36

1 Answers1

0

Focusing on the last part of the question:

Are there any other pros/cons that we are missing for both the approaches?

Another concern not addressed in this question or the linked one is handling concurrent updates to the data.

Suppose two users open the workflow in the workflow builder. It doesn't matter if the builder is using a GUI or text representation. Both users make some changes (which are not identical) and try to update the workflow. Presumably, you want to know if the changes conflict. (See note [2] below for how to detect this.)

With a single API, any difference in the two updates will result in a conflict that must be resolved, either automatically by the server, or by asking one of the users to merge the changes.

  • Pros: notice all conflicting changes, even if they don't modify the same node. Important if different steps of the workflow are interdependent.

  • Cons: potentially lots of false conflicts detected, requiring complex resolution logic or extra work by the users.

With multiple APIs that act on individual nodes in the workflow, only changes that affect the same node would result in a conflict.

  • Pros: only directly conflicting changes need resolution. Furthermore, the semantics of the APIs may automate resolution. See note [3].

  • Cons: changes which occur in different nodes but are nonetheless semantically conflicting be more difficult to detect.

[2] How to detect conflicts: tell each client the current (base) revision, and have clients report their base revision when sending an update. For example:

  1. Workflow is at revision A
  2. Client 1 gets the workflow at revision A
  3. Client 2 gets the workflow at revision A
  4. Client 2 sends an update to revision A
  5. Workflow is at revision B
  6. Client 1 sends a (different) update to revision A
    • this change potentially conflicts with revision B

[3] Examples of automatic resolution rules, which may or may not be desirable:

  • adding a new node is always safe
  • deleting a node can proceed regardless if the node was previously updated.
Anton
  • 111
  • Your point [2] is valid and that is exactly what we are planning to do. But it will work the same way with both the approaches. Calculating the diffs between 2 versions is a different problem and we are handling it outside this service. – Sarthak Jain Oct 15 '19 at 09:27