The Importance of a Well-Defined API Interface in Building a UI

Bluecore started with a proof of concept product that could be quickly iterated upon. We used Github as our “UI” where we could make updates to structured configuration files that would be used to determine the who, what, and when of our emails. Our customer success team needed to be fairly technical because they needed to update these files. This worked well in the beginning while we found product-market fit. However, as our customer base grew, this process no longer worked for 2 reasons:

1. Our customers wanted to have more control over and visibility into the emails they were sending out.
2. We would have to scale our customer success team linearly with the size of our customer base, which would be very expensive.

It was time to build a self-serve product with a UI! We made a few mistakes along the way, and through the process of fixing mistakes and creating new products, we’ve improved how we design and iterate.

One of our biggest mistakes in building our web application was not creating well-defined interfaces between our frontend and backend. Without these interfaces, our frontend engineers had to understand how the backend engineers stored the data. This allowed backend engineers to push more business logic to the frontend to handle. This further broke the principle of separation of concerns.

Why was this problem such a pain?

1. Changes to the frontend required a deep understanding of both frontend and backend code, which caused changes to be very error-prone and reduced the iteration speed.
2. The only way to really mitigate errors was to have thorough integration tests, which were hard to maintain because they also required a deep understanding of both frontend and backend code.
3. Changing how the underlying data was stored on the backend would mean lots of changes to the frontend as well.

Why did this problem happen in the first place?

1. Our engineers hadn’t really built a UI like this before.
2. We were trying to reuse as much of our backend code as possible.
3. The initial design didn’t take into account all the necessary features and so new things had to be added later on.

These issues could be overcome. However, most importantly, we were on a time crunch and therefore we didn’t spend enough time planning out what actually needed to be accomplished and how it should be done before diving in. In addition, we didn’t plan for the unexpected. There will always be surprises when building something big and new, so it’s important to build in time to rethink the design when these issues come up rather than hacking these additional features on later.

Note: As a startup, sometimes things just have to get done and you don’t always have the time and resources to plan as thoroughly as you want. BUT it can really help in the long run for maintainability and extensibility, so definitely try to allocate time for planning!

How do we avoid this in the future?

Over time we’ve come up with a process that we’ve used to define better interfaces for API endpoints. This involves a bit more planning upfront and has enabled us to build more maintainable features. We will go through the steps of this process and illustrate how it works using the example of building our campaign flow. This project involved deciding how to store the data, how to send the data to the UI, and how to lay out the UI.

1. Schedule a meeting with the frontend engineer, backend engineer, product manager, and designer. Go over the requirements and design. Start the conversation about what should be handled by the frontend and what should be handled by the backend.

Design mock of the campaign flow.

2. Work on the frontend and backend technical design separately. Decide on how you would ideally structure and store your data.

Each box represents the objects that the frontend and backend would ideally have.

3. Bring the technical designs together. You can be a full stack engineer deciding this yourself; however, this coordination is especially important when you have separate frontend and backend engineers. In this discussion, be sure to go over the requirements and any UX designs for the end product again. This will allow you to make sure that you have accounted for all possibilities.

4. Find the commonalities between the designs. This is likely to be an iterative process. It is possible that you will find that there aren’t enough commonalities between the designs. In our experience, this often occurs because the backend is not handling enough of the business logic. This forces the frontend to implement this logic. Remember that keeping as much logic on the backend as possible can allow you to change how you store, process, and compute your data down the road, giving you more flexibility in the long run.

We look for commonalities between the data presented. Initially, it seems like we will have a few separate objects. However, we end up having to go back to the drawing board and create a unified object that will be used for our entire flow. This allows our backend and frontend to have different data models with a common interface.

5. Make your API spec. This doesn’t need to be as formal as Swagger/Open API; it could simply be a shared document. Make sure that it is easy to iterate and update as it is likely that there will be changes needed as you write the code.

6. Have regular meetings to discuss unexpected complexities. These meetings should include the frontend engineer, backend engineer, product manager, and designer. This will allow you to make sure that you aren’t making design decisions in a vacuum that could negatively affect other engineers or the outcome of the project.

Over the past couple of years, we have had the opportunity to learn the hard way how important a well-defined interface is to testing, maintenance, and extensibility. Learning from our early missteps has allowed us to iterate more quickly and build high impact products for our customers!

Interested in working with us? Check out our careers page here: https://www.bluecore.com/careers