Quick answer: A custom API lets other software, such as a mobile app, a partner’s system or your own website, read and update your business data in a controlled way. Building one safely comes down to a few principles: expose only the data each consumer needs, require proper authentication, check permissions on every request, run everything over HTTPS, validate all input, limit request rates, log activity, and version the API so you can change it without breaking the apps that rely on it.
Businesses usually start thinking about a custom API when something needs to talk to their data that cannot today. A mobile app needs customer accounts. A wholesale partner wants live stock levels. The sales team wants orders to appear in the CRM automatically. Or an old internal system is being replaced in stages and the new parts need to share data with the old.
An API solves these problems, but it also opens a door into your systems. This guide explains how to build that door so the right people can use it and nobody else can.
When you need a custom API
Many modern tools already have APIs, and connector services such as Zapier can link them without code. You need a custom API when:
- Your data lives in a custom database or legacy system with no API of its own
- You are building a mobile app or single page web application that needs a back end
- Partners, resellers or suppliers need direct access to specific data
- Existing integrations are too limited, too slow or too fragile
- You want one consistent way for all your systems to reach the same data
If you are new to the idea, our explainer on what an API is covers the basics without jargon.
Step 1: Decide exactly what to expose
The safest data is the data you never expose. Before any code is written, list:
- Who will use the API. Your own app, specific partners, or the public?
- What each consumer needs to do. Read product data? Create orders? Update customer details?
- Which fields they need. A delivery partner may need an address and a phone number, but not order history or payment details.
Design the API around these use cases, not around your database tables. Exposing a table directly tends to leak internal fields, such as cost prices, staff notes or internal IDs, that nobody intended to share.
Treat personal data with extra care
If the API handles customer information, check your obligations under data protection law, such as the Data Protection Act in the UK. Keep personal data out of URLs, where it can end up in server logs and browser histories, and only return it to consumers with a clear need.
Step 2: Choose an architecture
Most business APIs today follow REST principles and exchange data as JSON. REST APIs use standard HTTP methods: GET to read, POST to create, PUT or PATCH to update, and DELETE to remove. They are well understood, work with almost every language and platform, and are easy to test.
SOAP APIs, based on XML, are still common in older enterprise and financial systems. If you need to integrate with those, a custom API can act as a translator, offering a simpler REST interface to your own apps.
Good design matters as much as security. Clear resource names, consistent responses and helpful error messages make an API easier to use correctly. Our guide to REST API design covers these principles in detail.
Step 3: Authenticate every consumer
Authentication answers the question “who is making this request?” The right method depends on who is using the API.
API keys
A long, random key issued to each consumer and sent with every request, usually in a header. API keys are simple and suit server to server integrations with trusted partners. They identify the application, not an individual user. Never put an API key in a mobile app or in JavaScript that runs in the browser, because anyone can extract it.
OAuth 2.0
OAuth 2.0 is the standard for letting users grant an application limited access to their data without sharing their password. It is what happens when you click “Sign in with Google” and approve a list of permissions. It suits APIs used by mobile apps and third party applications. It is more complex to implement, so use a well tested library or framework rather than writing it from scratch.
Token based sessions
For your own mobile app or web front end, a common approach is to exchange a username and password for a short lived access token, then send that token with each request. JSON Web Tokens (JWT), standardised in 2015, are a popular format. Keep token lifetimes short and provide a secure way to refresh them.
Whatever you choose, store secrets securely. Hash passwords with a slow algorithm designed for the job, such as bcrypt, and never store API keys or tokens in plain text where a database leak would expose them.
Step 4: Check permissions on every request
Authentication tells you who is calling. Authorisation decides what they are allowed to do. Many API security problems come from getting this wrong.
A classic mistake looks like this: a logged in customer requests /api/orders/1001 and sees their order. They change the number to /api/orders/1002 and see someone else’s. The API checked that they were logged in but not that the order belonged to them.
To avoid this:
- Check ownership or permission for every record, on every request, on the server
- Never rely on the app hiding a button as a security measure
- Give each consumer the narrowest set of permissions that does the job
- Separate read and write access, so a reporting integration cannot change data
Step 5: Encrypt everything in transit
Every API request should use HTTPS. Without it, keys, tokens and data can be read by anyone on the same network, such as public Wi-Fi. Redirecting HTTP to HTTPS is not enough for an API, because the first request may already have leaked credentials. Refuse plain HTTP requests altogether.
SSL certificates are becoming easier to obtain. Let’s Encrypt entered public beta in December 2015, offering free certificates with automated renewal.
Step 6: Validate all input
Treat everything sent to the API as untrusted, even from your own app. Validate:
- Types and formats, such as numbers, dates and email addresses
- Lengths and ranges, so nobody can send a 50 megabyte “name” field or order minus five items
- Allowed values, such as status fields that accept only a fixed list
Use parameterised queries or a trusted database layer to prevent SQL injection. Encode output properly if API data is ever displayed in a web page. Return clear error messages that help legitimate developers, but do not reveal internal details such as stack traces or database errors.
Step 7: Protect against abuse
Rate limiting
Limit how many requests each consumer can make in a given period. This protects your servers from runaway scripts and slows down anyone trying to guess passwords or scrape data. Return a clear response, such as HTTP status 429, when the limit is reached.
Pagination
Never return unlimited results. List endpoints should return data in pages, with a sensible maximum page size.
Logging and monitoring
Log who called which endpoint and when, without logging passwords, tokens or sensitive data. Set alerts for unusual patterns: a spike in failed logins, one key making far more requests than normal, or requests for many records in sequence.
Ability to revoke access
You must be able to switch off a key or token quickly if it leaks or a partnership ends.
Step 8: Plan for change
Your API will change. New features will be added, and some fields will need to change. Apps already using the API must keep working.
- Version the API, for example with
/v1/in the URL, and keep old versions running for a stated period after a new one launches - Add fields rather than renaming or removing them where possible
- Document everything. Formats such as Swagger let you describe endpoints in a machine readable file and generate interactive documentation
- Announce changes to consumers well in advance
Step 9: Test thoroughly
Build automated tests for every endpoint, including the unhappy paths: missing fields, wrong types, expired tokens and requests for records the user does not own. Before launch, have someone other than the original developer try to break it. For APIs handling sensitive data, a professional security test is worth the cost.
Where the API should live
You can build a custom API as part of an existing application or as a separate service in front of it. A separate layer is often useful with legacy systems: it gives new apps a clean, modern interface while the old system carries on underneath. This is a common first step in legacy system modernization.
If your website runs on WordPress, the REST API infrastructure arrived in core with version 4.4, and the companion plugin adds ready-made endpoints for posts and users. It is a reasonable foundation for content related APIs, though business data often belongs in a dedicated service.
FAQ
How long does it take to build a custom API?
It depends on the number of endpoints, the complexity of the business rules and the state of the underlying data. A small read only API is a much smaller job than one that creates orders across several systems.
Can I make an API public?
Yes, but public APIs need stronger rate limiting, clear terms of use, good documentation and careful monitoring. Many businesses start with private partner access.
Is an API secure if it uses HTTPS?
HTTPS protects data in transit, but it does nothing about weak authentication, missing permission checks or bad input. You need all of them.
Build it right the first time
A well designed API becomes the backbone that connects your apps, partners and systems. If you are planning one, see how we approach custom development.
