Should You Build an API Before Customers Ask?

Build an API before customers ask only when you can name the repeated workflow it will unlock and the team that will use it. Otherwise, you are probably turning an internal implementation detail into a public product before you understand the customer.

An API is not just another route in your backend. Once outside developers depend on it, you own a contract: documentation, authentication, errors, versioning, support, and the cost of changing behavior later. The right first move is usually to prove the workflow manually or through a narrow private interface, then expose the smallest stable surface that removes a real bottleneck.

Key takeaways

• Start with a customer workflow, not a belief that every serious product needs an API.
• Build a private or partner-specific test before committing to a public contract.
• Design one or two high-value operations and document how a developer completes a real task.
• Treat support, compatibility, and deprecation as part of the product cost.
• Delay a public API when the data model, customer, or core workflow is still changing weekly.

What job would the API make easier?

“Customers want an API” is not specific enough to justify building one. Ask what they are trying to do. Are they moving data between two systems? Triggering your product from an internal workflow? Embedding one capability into their own interface? Automating a task that is currently handled by a person?

Write the request as a workflow:

A developer at [customer type] needs to [complete a job] after [trigger], and we will know the API helped when [observable result].

If you cannot fill in those blanks, keep interviewing and watch how the customer solves the problem today. The Government Digital Service guidance on API documentation starts with user research because documentation and interface design should reflect developer needs, not the way the internal team happens to think about its system.

An API can be the wrong answer even when the request is real. A one-time export, a manual setup step, or a small number of contracted integrations may be better served by an operator-assisted process. The request matters; the implementation is still a hypothesis.

Test the workflow before you publish the contract

Start with the narrowest test that can change your decision. You could:

1. Run the workflow manually for one customer and record every input, decision, and output.
2. Create a private endpoint for one partner with an explicit owner and expiration date.
3. Share a draft OpenAPI description and a sample request with the developer who asked.
4. Watch whether they can complete the task without repeated explanations or custom exceptions.

This is not an argument against API-first design. Zalando’s API guidelines describe API-first as defining the interface before implementation and getting early feedback from peers and client developers. The useful distinction is between designing a contract early and promising a broad public surface before anyone has tested the workflow.

For an early product, a preview is valuable because it lets you test names, resources, error behavior, and missing capabilities while changes are still cheap. Microsoft’s API guidance recommends focusing on a few “hero scenarios,” shipping fewer features, and using previews and customer feedback before a first generally available release.

Expose the smallest stable surface

Do not publish your entire data model because it exists. Choose the smallest set of resources and actions needed for the proven workflow. A good first API may have one read operation, one write operation, and a clear way to observe failure. It does not need every admin setting, internal status, or future use case.

Before you expose it, check four things:

• Names: Can a developer understand the resource without knowing your database tables? Microsoft recommends names that reflect user scenarios and familiar concepts rather than implementation details.
• Errors: Does a failed request explain what the caller can fix? “Invalid argument” is not a useful contract when the caller needs to know which field or constraint failed.
• Change: Which fields can grow without breaking clients, and how will you announce a breaking change?
• Proof: Can someone outside the implementation team complete the hero scenario from the documentation?

The Google API design guidance treats resource names, standard methods, errors, versioning, and backward compatibility as separate design concerns. That is the warning: an API decision is bigger than choosing REST, GraphQL, or RPC.

Budget the promise after launch

The implementation may be the easy part. Microsoft’s guidance calls out the downstream work around an API: testing, documentation, client libraries, examples, and ongoing customer support. A public API creates a second product surface that has to remain understandable while the underlying application changes.

Make a small ownership table before launch:

Responsibility	Owner	First proof
Authentication and access	Named person	A test account can be created and revoked
Documentation	Named person	A new developer completes one task
Monitoring and errors	Named person	Failed calls are visible and actionable
Compatibility	Named person	A versioning and deprecation rule exists
Customer support	Named person	A caller knows where to report a problem

If every row says “the founders later,” the API is not ready to be a public promise. Keep it private, narrow the scope, or postpone it.

When should you wait?

Wait when the customer workflow is unclear, the same request means a different thing to every prospect, or the API would expose abstractions you are still changing every week. Wait when you cannot afford to answer integration questions. Wait when the request is really for a one-off custom feature and no second customer would plausibly use the same interface.

Build a preview when one workflow appears repeatedly, a developer can test it with real or safe data, and you can name the compatibility and support boundary. Move toward general availability only after the preview teaches you which parts are stable enough to promise.

FAQ

Does an API make a startup look more enterprise-ready?

Not by itself. A small, reliable interface with clear documentation can remove a real integration bottleneck. A large undocumented API can create more risk than value. Build for a workflow, not for a badge.

Should I build an API for one customer?

Possibly, if the customer has a valuable workflow and the agreement gives you a bounded learning opportunity. Keep the interface private or contract-specific until you know whether the same job appears elsewhere.

Is API-first the same as building the API first?

No. API-first means designing and reviewing the consumer-facing contract early. You can design the contract before implementation while still delaying a public launch until customer evidence and operational ownership exist.

Wrap up

Before writing production endpoints, interview the developer who asked, map the workflow, run one narrow preview, and write down who owns support and compatibility. If the API removes a repeated bottleneck, expand it carefully. If it only makes the architecture feel more complete, keep learning.

If you want peers to pressure-test the workflow, preview scope, and ownership table, bring the decision to the buildpurdue cohort.