Is this data as a result of business logic or is this content as a result of GUI logic?

Question

I'm aware of the general distinction between data and content, namely context, but here I have a case that is clearly causing a lot of confusion and debate within the company I work for.

There is a front-end team which manage an application which calls our data API. The confusion is that they want the content structured the way they are presenting it, because according them the structure implies domain knowledge (business logic) which they don't know anything about. The thing is, they came up with the structure in the first place... together with business. So is it business logic or GUI logic?

To illustrate, here's an example:

Our REST endpoint /car/123/repair/status returns:

{
   "status": "being_painted" /* actually an enumeration */
}

One customer journey scenario conjured up by the UX guy from the front-end team includes the concept of 'stages' in which the various repair statuses can be categorized into. This was discussed and agreed upon with our business product owner. The idea is that it provides a better visual overview to the end-user (not being business).

So instead of applying GUI logic to display 'stages' correlating to the 'repair status', they want us to provide it as data. Data that has no bearing on any IT process using a concept we don't officially know.

What they want:

{
   "currentStage": {
       "stage": "stage_recovery"
       "status": "being_painted"
    }
}

Is this business logic that should be part of the data API or is it GUI logic that should be part of the front-end application? Rephrased: should we provide such a granular API that it is completely specced for the highly specific presentational need or should we stick with just the statuses and create an API that only deals with data known to us internally?

One argument for providing statuses but not stages is the fact that statuses are based on the source data from our domain, while stages are based on the result of this (so not on source data). But I'm not sure how much of a real argument that is.

Answer 1

Let me correct one thing in your question which looks like a wrong assumption to me - "business logic vs. GUI logic":

GUI logic and business logic are not mutual exclusive.

Even if there are no other backend processes which use the "stage" field, there seems to be a business process for which the "stage" field is required. This business process may be completely interactive and GUI triggered, nethertheless it is a valid business process.

In fact, the correct categorization of repair status values into stages is definitely domain logic (which is very obvious to me, since I have no knowledge of that domain, and I would have to ask a domain expert for getting to know the possible stages and the categorization).

This leads to the question how you want your responsibilities shared between front end and backend:

• if you want the GUI as dumb as possible, and as much business logic as possible in the backend, provide the stage field from the latter

• if you want the GUI to take responsibility for certain kinds of business logic, you can let it derive the stage field from the repair status there.

Both strategies can sometimes be justified, depending on the circumstances, so we cannot give a clear-cut recommendation for you. It is an architectural decision which involves on how your development process is organized, how your team works and how you want to maintain and evolve your system.

Note, however, the second approach bears a certain risk, because if you are ever going to extend the number of possible repair status values, you must make sure it is not forgotten to extend the mapping to stages as well. And if this mapping is coded into the front end, whilst the status fields are in the backend, the chances are way higher it will be forgotten.

Answer 2

The core of your business logic and the business services that you provide are based on the domain model. Ideally your domain model is a meaningful abstraction of business data and context. By itself it should be something that you could reason about with the business in terms of the domain model and have it make sense to all parties. Furthermore any business services would accompany this domain model to provide business functionality, actions and processes in a way that the business and technology can both mutually reason about.

From your comments, it sounds as if the business owner agrees that this concept of "Stages" makes intuitive sense to the business and is something that is not abstracted from their mind as a visual or technical detail. While "stages" may only be realized in the form of visual presentation to the user, it is apparently significant enough to the business to be realized as a domain entity of itself.

You should treat it as such. It should be considered a separate yet related business entity that may or may not have defined business/functional services that can act on it.

As an exercise to help you understand and better define your technical services, start with defining the business domain model and functional use case scenarios. From here you can define the meaningful business services that your business or product owner can reason about. From here you can then take this as input to define the technical services that are going to be built.

When designing the technical services (REST, SOAP, MQ, etc..) then you can start factoring in other matters like decoupling components and providing a clean separation of concerns such that you optimize future reusasbility of services.