Designing APIs using Flexbase Control Flow

An 8 minutes read

In this section, we will look at FlexBase control flow in more depth from a business analyst's perspective so that you can start thinking in terms of breaking requirements into features (APIs) and modules

A feature is an API

First, a quick recap. When you work on requirements you can break an application into modules and features. At an atomic level a feature is nothing but an API. This is an important concept when designing applications using FlexBase.

Note: In FlexBase a feature is an API. We will use terms "feature" and "API" interchangeably. And a logical group of APIs makes a module.

FlexBase is an application development framework that helps build robust, scalable, responsive & extensible web APIs.

FlexStudio tool helps business analysts visualize requirements in terms of APIs & modules. They don't have to worry about technical details when designing APIs in FlexStudio.

If you follow a user story, you can easily break requirements into modules and features in Flexstudio. Let's look at an example,

A user story can say - "when user presses the submit button, a new customer record is created in database and an SMS & an email are sent to the customer."

This user story describes a user action (press submit button) which leads to a domain event (creation of new customer record). This domain event in turn triggers some other events like sending SMS / sending email to the customer. Now the question is, how can a BA visualize this story as an API?

This can be done as follows:

  1. The API is triggered from a user action (submit button in a form)

  2. The action type of the API is POST.

  3. It leads to creation of a new customer record in the database

  4. An SMS & an email are triggered to the customer when the record is created.

As simple as that.

In similar manner, you can start looking at other user stories. You can turn all user stories into one or multiple APIs. For example, another user story can be "when user presses view button, a list of recently added customers is obtained"

The API / feature version of this user story can be,

  1. The API is triggered from press View button user action.

  2. The action type of the API is GET.

  3. A query is fired which fetches the recent customers records

Now you should be able to appreciate how at atomic level features are APIs.

Flexstudio provides a visualization to business analysts to design these APIs as per the requirement. In Flexstudio you can define any API completely.

Components of an API

So, to design an API / feature in Flexstudio, business analyst must understand the composition of an API in Flexbase. Let's look at it here,

In Flexbase, every API or application feature is composed of 6 components:

  1. The starting point

  2. The action type

  3. Validations (plugins)

  4. Command

  5. Events

  6. Subscribers

The Starting Point

An API can be called from an application form (like a user pressing a submit button on a form). It can also be called from another application / API (like a shopping cart service calling APIs in shipping service)

Most of the user stories are written in two ways,

  1. When user takes an action, an event takes place in the application.

  2. An event in application or a system, triggers another event in the application.

So a business analyst usually knows the starting point of an API from the user stories. Either it is a user action or an application event.

The Action Type

Web APIs are written to respond to one of the HTTP request actions - GET, PUT, POST or DELETE. From database perspective you can think of these action types leading to Creation, Reading, Update or Deletion of records.

As you will note, for an API, specifying the action type is a standard practice.

Validations & Business Rules

An API call should not lead to any inconsistency in the system. Therefore, a request needs to be validated against system and business rules, before it starts making changes in the application.

An API should carry out these validations & business rule checks before a domain event occurs. (Note: for now think of domain event as creation, update or deletion of record.)

In FlexStudio, you can easily specify these checks. For example, before adding a new customer, may be you want to check that there should not be any duplication of customer records. So you want specify a isUnique check.

Other checks could be hasValidDateofBirth, hasValidAddress & so and so forth. In a FlexStudio, you can specify these validations in a sequence.

In DDD, these checks are also called policies. More about it in next section.

Till this point you have specified all the standard components of an API - the started point, action type and validations.

Commands, Events and Subscribers

These 3 API components exist in an architecture that implements eventual consistency & follows pub-sub design pattern. Flexbase does that. Let's understand each of these components.

Command

A command is a message that is passed to a command handler to carry out an action. Just like a command in real life, commands in Flexbase APIs are specified in imperative verb form. For example, AddNewCustomer, UpdateOldCustomer & FetchShippedItems.

The job of a command handler is to execute exactly what the command says. So, if you specify the command, you know that Flexbase command handler will execute it.

What you need to understand is that for describing an API, you are interested in specifying the command.

If you notice command is an obvious consequence of the feature / API itself. For example, if the main function of the API is to Add new customer to database, command generated in API will be AddNewCustomer.

As simple as that.

If you notice the components starting point, action type, validations and command are a standard construct whose purpose is to perform a particular action (AddNewCustomer).

Event

An event is an action or a state change in the application which could be of importance to other subsystems or systems. For example, addition of a new customer in database is an event. It can be of importance to email system, or SMS system.

An event can also be specified as a message in an event queue. Here's how,

Going back, when a command is given to a command handler, it does two things:

  1. It executes the domain event (like, saving the new record)

  2. It publishes the event message (new record saved) in the event queue.

Taking the above example, adding new customer to database is a domain event that has taken place in the application. This domain event happened because of the command AddNewCustomer. After the record is saved in the database, the command handler publishes an event in Flexbase event queue.

There are two possible outcomes - success or failure. For example, addition of new customer in database can be successful or it could fail. In case it succeeds, the event message that you would want to create in event queue is - NewCustomerSuccessfullyAdded. In case it fails, the event message that you would want to create in event queue is - NewCustomerAddFailed.

As you can see the events in event queue are specified in past tense.

From the API design perspective, you want to specify the command and the corresponding event. As you have seen command is an obvious outcome of the API definition itself and the event is a message that says if the action you wanted to achieve was successful or not.

Subscribers & Publishers

Once an event is available in the event queue, it can be subscribed by subscribers. Subscriber are end-points that listen for a particular event. And when that event occurs they can execute another process or call another API. This is the fundamental principle for pub-sub design pattern.

In the AddNewCustomer API example, you might want to specify two subscribers for the NewCustomerSuccessfullyAdded event - SendSMStoCustomer & SendEmailtoCustomer.

The job of SendSMStoCustomer can be to invoke an SMS application which sends an SMS to the customer. While, the job of SendEmailtoCustomer subscriber can be to invoke an email application which sends an email to the customer.

What you must appreciate here is that invoking of SMS and email application is asynchronous to addition of new customer record event.

When the two subscribers - SMS handler and email handler - complete their processes, they in turn have an option to publish their success and failure event messages in the event queue.

For example, SendSMStoCustomer subscriber can publish SMSSendtoCustomerSucceeded & SMSSendtoCustomerFailed events.

This is pub-sub design.

This way, you can continue to add events and subscribers in the API depending on the requirement.

Putting API components together

Now you should be able to appreciate that any API can be completely described in terms of it's 6 components

  1. Starting point

  2. Action type

  3. Command

  4. Validations

  5. Events

  6. Subscribers

Simple. Using these 6 components you can describe the entire application behavior. You don't need to understand any implementation detail or technicality. Yet this becomes a very useful input to the developers.

Summary

  1. When you are thinking of an API in FlexBase, first think about the standard specifications - API action type, starting point, validations & command.

  2. API actions - POST, PUT, GET and DELETE are standard. POST & PUT usually correspond to CREATE and UPDATE in database. GET corresponds to READ and DELETE to DELETE in database.

  3. The second part that you need to think is - does the domain event taking place in the API impact other systems or subsystems? If so, then you can create pub-sub design to handle it. Note: A domain event impacting other systems or subsystems is relevant for PUT, POST and DELETE actions. In GET action you are simply reading information. Strictly speaking there is not domain event happening that is changing the state of the system.

  4. Using FlexStudio, a business analyst can start designing APIs. This fills a major communication and design gap that exists in the software industry when converting requirements into code.

  5. What we have not covered here is writing user stories or writing requirement documents. We are assuming that business analysts are aware of these topics.

In next section we will look at an example of how to break requirements for an e-commerce site.