I’m often asked which is the better style of API: REST, GraphQL, or gRPC. My answer is always: “I’m not sure. What does your API model say?” At this point, I’m often met with blank stares or given an answer about some database. What I’m really asking is: “What problems does your API solve and why?” Once we understand the needs better through modelling our API, we can then determine what API interaction style(s) are the best fit for your API.
Why API modelling before you design?
Beginning API design from the database will often lead to poor quality APIs that fail to meet the needs of everyone involved. Instead, we must consider who will use our API, what capabilities our API needs to support, and how they plan to use it.
To better understand the difficulties of bottom-up API design, let’s take a project management example:
While the database may store all of the important data for your app, it doesn’t tell us what the users want to do. Rather, it tells us how some developers decided to store the associated data. If we simply start with the database design, we might end up with a CRUD-style HTTP API that looks like this:
- Create Project
- Read Project
- Update Project
- Delete Project
- Search Projects
- Create UserProfile
- Read UserProfiles
- …
While this might not be a bad start, it focuses too much on the database tables and not enough on the user’s needs. Our table names might be understood internally, but it may be foreign to those outside our team when they become the names of our API resources. Naming is primarily about communication.
API modelling helps us to establish better communication practices before we design our API. And since APIs are forever, we need to carefully consider the names we select for our resources. It also helps to draw out common understanding, sometimes called a ubiquitous language in domain-driven design, that can be used as a shared dictionary between your developers and product manager.
In addition, API modelling answers the question of why your API exists and what it plans to solve, before you decide how to design and build it.
“Weeks of programming can save you hours of planning.” – unknown
The process of modelling your API isn’t difficult and shouldn’t take too much time. I’ve consolidated the process into 5 steps, which I’ll overview for your below.
Step 1: Determine who needs your API
The first step in API modelling is determine who will use your API. They may be called participants, actors, or users. Unlike a user interface, APIs might be used both directly by developers and indirectly by end users. It is important to understand the needs of both parties. We also need to consider the kinds of applications and devices that may interact with our API in different ways.
When identifying participants involved in using the API, we may want to be a little more specific. Rather than just calling out developers as a participant, we may want to differentiate between internal developers, operations engineers, and external developers. The same could be said for differentiating end users: standard users, account administrators, and system administrators each have different methods and desired outcomes when consuming your API.
For our project management app, we might identify the following participants as a starting point:
- Project managers – create and oversee a project
- Project collaborators – participate in a project
- Project viewer – observe and report on a project
- Project management office admin – oversee the status of all projects and manage accounts
No matter how general or specific your list may be, identifying who will use your API is an important first step. As a bonus, this list list of participants will drive your API documentation efforts in the future, ensuring that they address the needs of the various developers and end users that will consume your API.
Step 2: Identify the desired outcomes
Your end users don’t care about your fancy databases or the elegant way to built your code; they care about the outcomes your API enables. For our project management API, this might include:
- Managing a project from start to completion
- Add collaborators to a project
- Subdivide a project into issues
- Track issue progress
- View incomplete issues
- View active projects
Notice that these outcomes will likely require one or more steps to accomplish the activity. For our next step, let’s decompose these outcomes into the steps that make it a reality.
Step 3: Map the steps required to achieve these outcomes
Outcomes are composed of steps, with each step being accomplished by a participant. Each step will be powered by one or more endpoints from your API. Decomposing outcomes into individual steps requires a deeper understanding of how your API will solve real-world problems. This insight is generally left to a subject matter expert (“SME”), so be sure to involve them in your API modeling process.
Revisiting our project management API, we can identify some of the steps required to support our desired outcomes:
- Managing a project -> Create a new project
- Add collaborators to a project -> Create a new user account; Find a user account by email; Add selected user to a project as a project member
- Subdivide a project into issues -> Add a project to an issue
- Track issue progress -> Mark an issue as started; Mark an issue as complete
- View incomplete issues -> Lookup a project; List incomplete issues for a project
- View active projects -> List active projects
While this isn’t a comprehensive list, it does demonstrate how our outcomes may map to a single step, or require multiple steps.
Step 4: Define your API model
Once all of the steps have been identified, you will begin to see an API start to emerge. This API will be composed of resources and actions. We can group these together to start to identify the resources and actions that we will need later, as we move into API design. Just remember that the goal of this step is to simply capture the APIs and methods to validate your API requirements – before moving into the more detailed process of API design.
Using our project management API, we might find the following resources and actions:
Projects
- Create a project
- Lookup a project
- List active projects
User accounts
Synonyms: Users
- Create a new user account
- Find a user account by email
Project members
Synonyms: Collaborators
- Add selected user to a project as a project member
Project issues
Synonyms: Tasks
- Add a project to an issue
- Mark an issue as started
- Mark an issue as complete
- List incomplete issues for a project
Notice how our outcomes and steps start to help us identify the resources associated with our API. They also help us to see how the API will be used, providing a hint to what our eventual API design may look like. Just keep in mind that these are candidate resources – we may not need them all, or we may need some that we haven’t identified yet. That’s the purpose of API modelling – to create a rough sketch of our API before we do the harder work of mapping it to HTTP and building it.
Step 5: Validate your API model
The final step in modelling your API is to validate it against known requirements. Like a good quality assurance (QA) team, your job is to ensure that your API will meet the requirements of everyone using it. Use wireframes, user stories, test cases, and other requirements to verify that your API model can meet the needs currently identified.
As you validate your APIs, look for participants, outcomes, and steps that are missing. You may also want to make notes about APIs that have dependencies on other APIs or that may experience heavy usage. While not necessary, this may guide some of your decisions as you move into the design and development phases.
Wrap-Up: Preparing for API design
At this point, you know a little more about what outcomes your API needs to support, the steps to get there, and what it may look like. Now, you can start to determine what style of API design is best for your API:
- REST
- GraphQL
- gRPC
- A combination of two or more of the above
For our project management example, we may decide to use a resource-based approach and apply REST constraints. In this case, we may map some of our steps to the following endpoints:
[TODO: image of outcome steps to endpoints]
Of course, moving from modelling to design doesn’t happen automatically. The API design process starts with the model we created and applies the principles of HTTP and our chosen API style(s) to create an API design that we code against.
If you are interested in more details into how API modeling works and how to go from modeling to design, pick up a copy of my book, “A Practical Approach to API Design”.