IntegrationCustom softwareRequirementsBudget
Custom API development: when to build your own API, and how to scope it
11 min read
Build a custom API when other programs need reliable access to your data or processes: your own mobile app, a partner's system, a customer portal, or your internal tools. If all you need is for two off-the-shelf products to talk to each other, an existing connector or an integration platform is often enough. A custom API is a product in its own right: it has to be designed, documented, secured and maintained.
If "API" is still a fuzzy term, start with our plain-English explanation of APIs. This guide is for buyers who already have a project and want to know what to ask a development partner for.
Three situations where a custom API pays off
Opening your data to partners or customers
A distributor wants live stock levels. A key account wants to push orders straight from its ERP instead of emailing spreadsheets. A referral partner wants to track the files it sends you. In each case, an API replaces file transfers, double entry and phone calls. It is also a commercial asset: a customer whose systems are wired into yours is far less likely to switch suppliers.
Powering your own app or portal
A mobile app, a customer portal or an admin back office should not read the database directly. They go through an API, which centralises business rules and permissions so every screen applies the same ones. That is the standard architecture of modern business software, and what lets you add a new front end later without rewriting everything.
Connecting internal systems that were never meant to talk
Your legacy ERP only exposes a database, your scheduling tool only imports CSV files, your CRM has an API but not the fields you need. An intermediate API built for you becomes the single point of exchange: it translates, validates and logs. Our guide to integrating a custom app with an existing ERP covers this case in depth.
Private, partner or public: decide the audience first
The audience changes the effort far more than the technology does.
| Audience | Who calls it | What it demands |
|---|---|---|
| Private | Your own apps and internal tools | Clean design, tests, internal documentation |
| Partner | A known list of companies | Contracts, per-partner keys, sandbox, support |
| Public | Anyone who signs up | Self-service onboarding, quotas, abuse handling |
Most businesses need a private API first and a partner API second. A truly public API is rarely the right first step for a company whose core product is not the API itself.
When you do not need one
- A native connector already exists, maintained by one of the vendors: start there.
- The flows are few and simple: an automation platform such as n8n, Make, Zapier or Power Automate is often enough. Our n8n vs custom code comparison shows where those tools break.
- A daily file exchange does the job: a well-built scheduled export is more robust than a poorly designed API.
- Nobody will call it yet: an API built "for later" without a first consumer produces a contract nobody has validated.
What a production-grade API includes
An API that works in a demo is not an API ready to be opened to others. Here is what makes the difference.
| Component | What it is for |
|---|---|
| OpenAPI contract | Describes every endpoint, its parameters and its responses |
| Authentication | Knowing who is calling: API keys, OAuth 2.0 for third parties |
| Object-level authorization | Checking the caller may see THIS order, not just orders |
| Versioning | Evolving the API without breaking existing integrations |
| Rate limiting | Protecting the service from greedy or malicious callers |
| Pagination and filtering | Never returning a hundred thousand rows in one response |
| Idempotency | An order sent twice is only created once |
| Webhooks | Telling partners something changed instead of them polling |
| Explicit errors | A clear message and a stable code for every failure case |
| Logging | Knowing who called what, when, and with what result |
| Sandbox environment | Letting partners build without touching production |
| Public documentation | Examples, a getting-started guide, announced changes |
The OpenAPI contract deserves a special mention. It is an open standard whose version 3.2.0 was published on September 19, 2025 (official specification). Written before the code, it acts as the technical specification: partners can review it, tools generate documentation and tests from it, and it is easy to hand to another provider if you change.
REST, GraphQL, webhooks or files
| Exchange style | When to choose it |
|---|---|
| REST | The default: clear resources, varied partners |
| GraphQL | Many different screens with very different read needs |
| Webhooks | Notifying a third party that an event happened |
| Scheduled files | Large volumes, legacy systems, nothing urgent |
| Message queues | High-volume internal flows that need retry on failure |
Real APIs usually combine several: REST to read and create, webhooks to notify, a file export for history.
Security: the flaws that keep coming back
OWASP, the reference foundation for application security, publishes an API Security Top 10 (2023 edition). The first five, in business terms:
- Broken object-level authorization: a partner changes a number in the URL and reads another customer's order.
- Broken authentication: tokens that never expire, passwords that can be guessed endlessly.
- Broken object property-level authorization: the API returns fields that should stay internal (margins, private notes) or accepts changes to fields that should be read-only.
- Unrestricted resource consumption: one caller saturates the service or blows up your hosting bill.
- Broken function-level authorization: a read-only account manages to delete records.
None of these show up in a demo. They are prevented by design (permissions checked on every request, responses limited to what is needed), by automated tests, and by a penetration test before third parties get access. For the rest of the application, see our security essentials for business applications.
APIs and personal data
As soon as an API carries names, emails or addresses, data protection law applies to every exchange: the GDPR in Europe and the UK, and equivalent rules elsewhere. Three habits reduce the risk: expose only the fields each partner needs, log access so you can answer a request or investigate an incident, and put a data processing agreement in place with every partner that receives personal data. Our GDPR checklist for business applications goes further.
What drives the cost of a custom API
Price ranges published online diverge widely because they are not describing the same thing. Cost depends on six factors:
- the number of resources and operations (reading stock levels is not creating an order with its validation rules);
- the complexity of the business rules the API enforces;
- how many systems sit behind it, and their condition;
- the security level required: external partners, sensitive data, penetration testing;
- documentation and partner onboarding;
- availability requirements: an API taking orders overnight is not monitored like an internal lookup service.
On top of the build cost comes the running cost: hosting, monitoring, security updates, new versions. For how estimates are built, read what a custom business application costs.
An API lives on after delivery
Once third parties build on your API, you have made a de facto commitment. Three workstreams continue after go-live.
- Monitoring: response times, error rates, call volume per partner. An alert should fire before a partner has to call you.
- Security updates to the components it relies on, as vulnerabilities are published, without waiting for the next feature release.
- Evolution: new fields, new operations, successive versions. Every breaking change is announced, dated, and paired with a period during which the previous version remains available.
Budget this from day one, as for any software in production. Our guide to business application maintenance explains what it covers.
Questions to ask your development partner
- Do you write the OpenAPI contract before the code, and will I review it?
- How do you check object-level permissions on every request?
- What versioning and deprecation policy do you propose?
- Which automated tests ship with the API?
- Who monitors the API in production, and how am I told about incidents?
- What do we receive if we change provider: code, specification, deployment scripts, access? Rights are defined case by case in the contract, so read that clause carefully.
Common mistakes
- Mirroring the database. Exposing tables as they are freezes your internal structure: you can no longer change it without breaking partners. The API should reflect the business (an order, a case file), not the storage.
- Opening without a sandbox. Partners then test in production, on your real data.
- Ignoring failure cases. What happens when a partner orders an item that was discontinued yesterday? Quality is decided there, not on the happy path.
- Undocumented changes. A field renamed without notice breaks an integration on a Friday evening.
- Building alone. The first partner or app consuming the API should help design the contract.
Where to start
- Name the first consumer: which app or partner will call the API, and to do what.
- List the operations that first use case needs, and nothing more.
- Have the OpenAPI contract written and reviewed by that first consumer.
- Build, test, open to that one consumer, then widen access.
When the API powers a portal, a mobile app or an admin panel, the safest move is to see the screens that will use it before building it. We create a free visual prototype, presented on a video call within 5 business days: it reveals the data each screen needs, and therefore the API contract.