I've been working on identifying gaps and improving our API. Initially, I discovered numerous endpoints that were missing, and I initially thought we needed to add them because having more endpoints is better, right? However, as I began researching further, I realized that adding too many endpoints could pose a security risk by exposing more information than necessary. This led me to consider how I could determine which API endpoints are essential and should be added to our product roadmap. This train of thought inspired me to create a scenario to help clarify my approach.
Imagine you're building an API for a food delivery app. Your main entities include restaurants, customers, menus, orders, payments, and delivery drivers. Naturally, you might start designing endpoints around these resources:
- GET /restaurants
- GET /menu-items
- POST /orders
- GET /orders/{id}
- POST /payments
At first glance, everything looks good. You have endpoints to create, retrieve, and manage the various objects in your system. However, here’s an important question: Can someone actually order dinner using your API?
This question might seem obvious, but it highlights a crucial distinction in API design. A customer doesn’t wake up thinking, “I need to make a POST request to the orders endpoint.” Instead, they think, “I’m hungry, I want a burger, and I want it delivered before my next meeting.”
Customers think in workflows, while developers build integrations around those workflows. Therefore, APIs need to bridge the gap between these two perspectives.
The Problem with Designing APIs Around Resources
Let’s go back to our food delivery app. Imagine a developer is integrating your API into a restaurant's own ordering system. Their goal is to allow customers to browse the menu, customize a meal, place an order, pay, and track delivery all without ever visiting your app.
You've provided endpoints for restaurants, menu items, orders, and payments. However, when the developer begins building the integration, they encounter several problems:
- They can retrieve a menu but cannot determine which items are currently unavailable.
- They can create an order but cannot customize a burger with extra toppings.
- They can submit a payment but cannot verify whether the payment was successful.
- They can retrieve an order but cannot tell when the driver picks it up.
- They can view an order but cannot cancel it after submission.
While you technically have an API that exposes all the major resources, the developer still cannot deliver the experience that their customers expect. This situation arises when we focus too much on the data our system stores and not enough on what people need to do with that data.
Start with the Customer's Journey, Not the Data Model
Instead of starting with resources like restaurants, menu items, and orders, let's start with the customer. What does the process of ordering dinner actually look like?
The Food Delivery Journey
A fictional customer ordering a burger
- Find a restaurant: Browse nearby restaurants and check whether they are accepting orders.
- Build a meal: Choose a burger, add toppings, select a side, and customize the order.
- Place an order: Submit the order and receive confirmation.
- Pay for dinner: Submit payment and receive confirmation that the transaction succeeded.
- Track the delivery: See when the restaurant accepts the order, when the food is ready, and when the driver is on the way.
- Resolve a problem: Cancel an eligible order, report a missing item, or request help.
Now we have a useful overview of the customer workflow. We can use each step to identify what functionalities the API needs to support.
Map the Workflow to API Capabilities
Once we understand the journey, we can translate each customer action into an API requirement:
| Customer Action | API Capability |
|---|---|
| Find a restaurant | Search and filter restaurants |
| Browse the menu | Retrieve menu items and availability |
| Customize a burger | Submit item options and modifiers |
| Place an order | Create an order |
| Pay for dinner | Process and verify payment |
| Track delivery | Retrieve order and delivery status |
| Receive updates | Subscribe to order status webhooks |
| Cancel an order | Cancel eligible orders |
| Report a missing item | Submit a support request |
Notice that we’re no longer just thinking about whether we have an endpoint for orders or restaurants. We're considering whether the API supports every action required to complete the entire experience. This perspective is where product opportunities begin to emerge. For example, if customers can create an order but cannot retrieve real-time delivery updates, we could introduce a polling endpoint, but would that actually provide the best experience? Perhaps webhooks would be a better solution. Instead of repeatedly asking the API whether the order has changed, the system could notify the integration when the order status changes from preparing to out for delivery, for example.
The right solution comes from understanding the workflow first.
Not Every Missing Endpoint Deserves to Be Built
This is where product management plays a vital role. Suppose customers are complaining that they can't modify an order after submitting it. Your first instinct might be to create an endpoint like:
- PATCH /orders/{id}
While this might seem like a simple solution, it's important to consider a few critical questions before building it:
- Can customers modify an order after the restaurant has started preparing it?
- Should they be allowed to change their delivery address?
- What other restrictions should be in place?
By approaching API design with a focus on customer workflows, you can create a more intuitive and efficient experience that meets the needs of both users and developers.
![Physical AI Safety and Alignment — Ch.03: AI Safety for Embodied Systems [EN]](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fihl3p3ejnjtkglocdt61.png)
![Physical AI Safety and Alignment — Ch.02: Functional Safety for Physical AI [EN]](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fayunvlni5npg3svhj9if.png)
![Physical AI Safety and Alignment — Ch.01: Physical AI Risk Taxonomy [EN]](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Ff974a0z59f5l12538pzp.png)