Designing API-first

All good design processes start by understanding a business or customer problem and then working out the details until you get to a point of confidence through research to actually build the thing.

The truth is, all good development processes start in the same way. You can't define and design an API without understanding the problem it aims to solve. "Do we already have an API that can provide this if we extend it?", "Should we build a lightweight, and new, API to send these data?", "Is this is even the right problem to solve?" and so on.

Whilst I don't work on constructing or crafting the APIs that I design customer solutions with, I do keep a tight eye on how we're designing the API so I can best understand how we might go about designing a frontend solution that takes advantage of these data.

Building a strong foundation

When I first started working alongside development teams, I found that in most places I worked they operated in a bit of a silo. Design was seen as the paint on top of the technical solution, and whilst we might work closely with mobile engineers to ensure what we designed got built correctly, we didn't really stay close to the backend engineers crafting the APIs.

Over time I got super curious. We send data to our frontends via this mysterious thing call an API, what is that and how can I better understand it to know the impact it might have on my work?

An API, or Application Programming Interface, is a mechanism by which you can send or receive information over a network to update or interact with an interface. There's lots of different methods you can utilise such as POSTing something (sending it), GETting something (receiving it), DELETEing something (deleting it...) or PUT/PATCHing it (modifying it).

As designers, we should care about what data is being sent around because it inherently defines what we might show to a customer or what controls they might be able to interact with.

Making APIs tangible

Let's say you have a form that you want to allow a customer to enter their name and email into. Understanding that this is an input that allows the customer to send data to a server to store this information is super handy. This means that submitting this form would send a POST request via the API to your server to append these data to the database.

[  
  {  
    "name": "Will Smith",
    "email": "will@freshprince.com",
    "weapon": "slap"
  }
]

But lets say you decide after the API is built and the success criteria are defined, that you now want a customer to be able to add their phone number. In this case, firstly the API isn't built to handle a number or to send that particular request, so now the backend team will have to modify the API (and also importantly, the database) to understand that a number can also be sent.

Sounds easy right? But imagine if you're making lots of these tiny changes, things like splitting name into firstName and lastName. In most companies, the backend work will start before the build phase begins. This means that any change has a risk of derailing the approach that was originally conceived by the backend team.

You hopefully already had some thoughts, sketched some ideas and started to ideate, but hadn't finished with your design by the time you raise these changes. This is good, you're working in an agile team, but you're also at a point of increasing project scope and increasing the project risk.

De-risking design and APIs

One exercise I like to do to prevent as much of this risk as possible is to design API-first. By designing the API in tandem with the backend engineers, you de-risk future problems. You can eek out the edge cases and plan for possible future adaptability together.

"If I decided to add in the need for a mobile number to be sent too, would that be a lot of extra risk? This idea is still being considered but isn't final"

A great way to do this is to build out your foundation together via early stage workshops. Recently I've introduced the practice of including a representative across each of our respective teams at the very start of the design process, when we're discovering the problem to solve. This means we have Design, Product, Mobile, CloudApps (backend) and QA in the room (sometimes also customer support or ops depending on the project).

Including these teams early means we define edge cases from the outside and design a flexible API and design solution that works for all teams across build, testing and production.

We've started workshopping all of this work inside of FigJam and it's been game-changing.

Last year, FigJam introduced the ability to include code blocks in your diagramming experience. This opened FigJam up to being super useful for engineering teams who are writing particular code and want to connect the dots. I noticed a few team members were using it to connect their APIs to mobile code which helped them to better visualise how the data would pass down and be rendered.

An image of a FigJam canvas with API documentation pointing to different Wireframes to show where the data is passed to in each case

I decided that it made sense to me, as a designer, to include this type of thinking into my flows too. So I started to get the teams to share their API docs with me so that I could include them as flow starting points for certain wireframe screens. Now, the connection between what data we expect, when we expect to receive it, and how it changes the view was all in one place.

When QA then came to test the edge cases, they knew when we'd expect to have received (or sent) data to or from the API, and in turn how that would impact the user interface. All teams would be on the same page, from the start to the end.

How this is impacting our shipping process

Since taking this approach, we've seen several cases where the time to delivery has been significantly reduced, that the edge cases we find aren't show stoppers because we knew what to expect from the start, and that our teams could all be aligned from the outset.

Our end-to-end QA process is significantly improved because the data they test with in Postman is aligned to the docs and flows we have in FigJam, and there's very little left to ambiguity.

This is still the exception and not the rule, we've been trialling it in our team because my knowledge of code allows me to suggest and test these approaches whilst understating what the APIs mean and why it's useful. Onboarding other designers and teams to this idea will likely be challenging because the value isn't immediately obvious, and the lack of technical understanding will be a limitation.

But, this is something I see as a great opportunity for teaching. I've been putting more and more energy into teaching my team how to understand the raw basics of coding, focusing initially on basic JavaScript as part of Figma plugin development, but slowly moving into understanding how data passes between platforms and why this matters to their day-to-day.

If you're a designer who's comfortable in the world of code, or who's interested to learn more about it, I'd highly recommend reaching out to your backend engineers to start a discussion around API design and its place in the design process.