“Understanding user personas is critical to making an API successful,” I wrote in May 2023. Unfortunately, most people are still building their APIs without having that understanding. What happens, in the end, is that the purpose of the API you’re building is unknown. You build a solution that’s so abstract it can solve almost any problem. Because the API is not specific, it’s hard to understand and integrate with. What can you do to improve this situation? Stay with me to learn more.
This article is brought to you with the help of our supporter, n8n.
n8n is the fastest way to plug AI into your own data. Build autonomous, multi-step agents, using any model, including self-hosted. Use over 400 integrations to build powerful AI-native workflows.
Consumers can only use what they can understand. If an API is too complex, people steer away from it. If it’s too simple and it lacks depth, people can’t use it to fix their problems. If it’s too concrete, there certainly are problems it can’t solve. If it’s too abstract, it’s hard to integrate with. You see where I’m going with this. It’s not easy to come up with a solution that makes everyone happy. The two extremes are APIs that simply mirror an existing database structure, offering a CRUD, and APIs that implement solutions to very concrete problems. Let’s see how you can give meaning to a generic CRUD.
A generic CRUD is simply an API that offers all the reading and writing operations of an existing database. Instead of having operations that reflect use cases, these APIs offer a way to get information and manipulate data. In a way, what they offer is a generic interface that consumers can, in fact, use to fulfill almost any use case. As long as the underlying database supports it, of course. The tricky thing is making it easy for consumers to fulfill their use cases with a very generic API. That’s where workflows come in. You see, one thing workflows do very well is convert a list of otherwise meaningless API requests into a use case that’s relevant to a particular group of consumers.
As an example, imagine you have a CRUD for a simple employees database. There’s a table for employee information, another table for roles, and another one for departments. The relational model is quite simple. Each employee can belong to a single department and can have only one role at a time. Let’s say you want to onboard a new employee as a manager of the support department. To do that, you’d first get the IDs for the manager role and the support department. Then, you’d create an employee record with the corresponding role and department IDs. Wouldn’t it be great to, instead, have an operation called “onboard” that would do everything for you? Let’s dig in.
We’re creating a new operation called “onboard” that will perform a series of API requests. If successful, it will create a new employee and correctly assign it to a department and a specific role. The “onboard” operation is, in fact, a workflow. Its input is the information about the employee we want to onboard, including the name of the department and the role. Note that we’re not using department and role IDs. Instead, the “onboard” operation translates the names into their corresponding IDs, and fails if the department or role don’t exist. Then, it will attempt to create a new employee with all the information provided, plus the obtained department and role IDs.
This workflow makes at most three requests to the CRUD: one to search for a department, one to search for a role, and the last one to create an employee. The workflow is extremely simplified, but you can imagine adding other attributes to the employee we’re creating. The point I’m making is that it’s possible and simple to aggregate several CRUD operations into a single workflow that solves a real use case. Even better, there are systems that let you convert a workflow into an API and execute it by making an HTTP request to a specific endpoint. In that case, you could end up with a new API that would replace a few CRUD operations.
Is this approach better than studying user personas and designing your API to fulfill specific use cases? I don’t think so. However, I think this approach has the benefit of adapting any existing CRUD to specific use cases. It’s also valuable during design time, as it lets you identify and even prototype specific operations before actually implementing them. If you’re working with a workflow engine that’s easy to operate by non-technical users, you could even have product managers do this kind of work.
