Take 40% off Designing APIs with Swagger and OpenAPI by entering fccponelat into the discount code box at checkout at manning.com.

“Any organization that designs a system (defined broadly) will produce a design whose structure is a copy of the organization’s communication structure.”

— Melvin E. Conway

Team structure

José has a new project and is looking to make a team. He goes through the list of his employees and looks at their skills and the kinds of projects that they’re involved with at the moments. The table below shows the non-functional requirements for the app José has in mind.

Table 1. Requirements Checklist

After finding some suitable candidates among his staff—Nidhi and Max—José sets up a meeting. Both developers have worked with José for a while and have shown their aptitude for learning and solving problems in unique ways.

Both readily agree to join the project, so we now have a three person team. Being the initiator, José acts as the project lead. The roles for the developers are not defined yet. We will do that next.

In their first meeting, José presents the plan based on his notes about the functional as well as the non-functional requirements. Nidhi tells him that, if they want to expand into the mobile realm later, they should work on a clear separation between backend and frontend. “That way”, she says, “we can have a backend with an API that different clients, such as our web application and then later the mobile application, can use!” “Great”, says Max enthusiastically, “then we can build an SPA, a single-page-application. I’ve experimented with React lately, and I think we can use that here!”

The three of them keep talking, and everyone seems hooked on the project. “However, José”, Nidhi adds, “remember that I have a few clients to support. We should try and work independently and asynchronously as much as possible. We can’t always meet to sync up.” Max nods in agreement, “Same here.”

In this discussion, the developers have suggested an architecture in which backend and frontend are two separately developed components, and Max already has a technology suggestion for the frontend. Before we move on, let’s first agree on what frontend and backend means in the context of a web application:

• The frontend is everything that happens on the user’s computer in their browser. The frontend is made with HTML, using JavaScript for interactivity. Max talked about React, which is a JavaScript framework for creating web application frontends.
• The backend is whatever happens on the server of the web application’s provider. Backends can use many different programming languages and frameworks and typically use a database to persist data.

The setup and the developers’ interests and availability naturally lead to a team structure with one frontend developer and one backend developer:

• Nidhi implements the backend
• Max implements the frontend

José’s first non-functional requirement about being able to build the application with two developers is met. We look more closely at the technology and the process for building each part later in this book.

API-driven architecture

José’s eyes light up after hearing the word API out of Nidhi’s mouth. His team has integrated a few APIs into client projects, for example, for sending SMS notifications or integrating e-commerce data or for marketing automation. To date, however, they have not built their own. “We could release this API later so that people can build stuff”, he suggests, “maybe some smart device that lets my pet sitter in automatically? Or something for my voice assistant?”

With everything that’s possible with an API-driven architecture, his second requirement about being able to work with an external agency for building a mobile app is easily fulfilled. And so is the third requirement of experimenting with new technology, as it’s the first time that José’s company has built an API of their own.

Traditional web applications run backend code that dynamically generates the HTML for the frontend. In an API-driven architecture, however, the frontend generates HTML with client-side JavaScript code based on the API responses from the backend, which typically are in JSON format. That way, the backend is disconnected from the presentation logic on the client.

Figure 1. Architecture and Development Team

The plan

In our setup with its API-driven architecture, the backend and the frontend developer can work autonomously, but it requires them to agree on the API beforehand. As you might know, you can use OpenAPI to create a formal description of an API. And there are tools that help in the process of building an application based on said OpenAPI description.

We have a team now and we have the basic architecture of the software. What’s missing is a plan. The purpose of this plan is to go from idea to implementation. As there are two parts of the implementation that each developer tackles individually, the plan needs to include the immediate step of designing the API. As the basis of the API design, the team first needs to create a domain model.

Putting everything together, the team writes down the following actionable steps:

1. In another whiteboard session, they jointly create a domain model.
2. Max creates the first draft for their API design.
3. Nidhi reviews that draft.
4. Both agree on finalizing the specification, or make edits and review again as necessary.
5. Both work independently on their parts of the implementation.
6. After completion, they integrate their code into one application.

Here is what our domain model looks like:

Figure 2. Action Plan

Now José’s team is ready to put their plan into action.

If you want to learn more, check out the book on Manning’s liveBook platform here.