From Designing APIs with Swagger and OpenAPI by Josh Ponelat and Lukas Rosenstock
This article shows ways to synch your architecture to your team composition for a new project, and how to start planning your project.
“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
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 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.
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.
Figure 1. Architecture and Development Team
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:
- In another whiteboard session, they jointly create a domain model.
- Max creates the first draft for their API design.
- Nidhi reviews that draft.
- Both agree on finalizing the specification, or make edits and review again as necessary.
- Both work independently on their parts of the implementation.
- 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.