An API (application programming interface) is a set of rules that lets one piece of software ask another piece of software for information or to perform a task. Your website uses one when it shows a Google map, takes a card payment through Stripe or PayPal, or adds a new subscriber to your Mailchimp list. You never see the API itself. You see the result: the map loads, the payment goes through, the contact appears in your list.
If you run a business, you do not need to write code to make good decisions about APIs. You do need to know what they are, what they can and cannot do, and what to ask a developer before you depend on one.
The restaurant analogy, and where it stops working
The usual explanation is a restaurant. You (the customer) do not walk into the kitchen. You read the menu, tell the waiter what you want, and the waiter brings it back. The menu is the list of things you are allowed to ask for. The waiter is the API. The kitchen is the other company’s system.
This works as far as it goes. It shows the most important idea: an API lets you use someone else’s system without needing access to its insides.
Where it falls short is that a real API also has rules about who can order, how much they can order and in what format the order must be written. Those details are what make an integration reliable or fragile, so we will come back to them.
How an API request actually works
Most modern web APIs follow the same pattern:
- Your system sends a request to a web address (an “endpoint”), such as one that means “create a new customer” or “get today’s orders”.
- The request includes credentials, usually an API key or a token, so the other system knows who is asking.
- The other system checks the request, does the work and sends back a response: the data you asked for, a confirmation, or an error message explaining what went wrong.
- Your system reads the response and acts on it, for example by showing a “thank you” page or saving an order number.
Responses are usually written in JSON, a simple text format that both people and programs can read. Older systems often use XML.
A worked example: an online order
Say a customer buys a product from your WooCommerce store. Behind one click, several APIs may be talking:
- The checkout sends the card details to your payment gateway’s API, which replies “approved” or “declined”.
- The store asks a shipping carrier’s API for a rate and later for a tracking number.
- An accounting integration sends the sale to QuickBooks Online or Xero through their APIs so nobody types it in again.
- Your email platform’s API adds the buyer to a customer list.
Each of these is a separate conversation between two systems, using rules that the provider publishes.
Types of APIs you will hear about
REST and SOAP
Most web APIs built in recent years are REST APIs. They use ordinary web addresses and standard HTTP methods (GET to read, POST to create, PUT to update, DELETE to remove) and usually return JSON. They are fairly easy for developers to work with.
SOAP is an older, stricter standard based on XML. You still find it in banking, government, travel and large enterprise systems. It is not “worse”, but it takes more setup, and developers who know it well charge for that knowledge.
Public, partner and private APIs
- Public APIs are open to any developer who signs up, such as the Google Maps, Twitter or Mailchimp APIs.
- Partner APIs are shared with approved businesses only, often after a contract.
- Private (internal) APIs connect your own systems, such as your website and your stock database. Many businesses build these without calling them APIs.
Webhooks
A webhook is an API call in reverse. Instead of your system asking “has anything changed?” every few minutes, the other system calls you the moment something happens: a payment succeeds, a form is submitted, a subscription is cancelled. Webhooks are faster and lighter than constant checking, and payment providers such as Stripe use them heavily.
Why APIs matter to a business owner
They remove double entry. If staff copy orders from your website into accounting software, or leads from a form into a CRM, an API integration can do it automatically and without typos.
They let you rent instead of build. You do not need to build a mapping system, a card processor or an SMS gateway. Google, Stripe and Twilio already did, and they sell access through APIs.
They keep your options open. If your systems talk through APIs, you can replace one part (say, your email platform) without rebuilding everything else.
They make new products possible. A mobile app, a customer portal or a partner integration all need a way to reach your data. An API is that way in.
What can go wrong
APIs are reliable, but an integration is only as good as the planning behind it. The common problems:
- Rate limits. Most providers cap how many requests you can make in a period. Go over and requests fail until the limit resets. A busy sale day can hit limits that never showed up in testing.
- Changes and retirements. Providers release new versions and retire old ones. They normally give notice, but someone has to read the notices and update your code. Twitter, for example, switched off version 1 of its API in 2013, and integrations that had not moved to version 1.1 stopped working.
- Outages. If the other service is down, your integration needs to fail gracefully: queue the request and try again, rather than lose the order.
- Security. API keys are like passwords. They should never sit in public code or in a shared spreadsheet, and each one should have only the permissions it needs.
- Data mismatches. Your system calls it “client”, theirs calls it “account”, and the fields do not line up. Mapping data between systems is often the slowest part of a project.
Questions to ask before you build on an API
Before you approve an integration project, ask your developer or agency:
- Is the API documented and stable? Good documentation, version numbers and a change log are good signs. Some providers also publish a machine-readable description of their API using a format such as Swagger, which makes testing and integration faster.
- What does it cost? Some APIs are free up to a point, then charge by request or by account tier.
- What are the limits? Requests per minute or per day, data size, and how many records you can fetch at once.
- How does authentication work? API key, OAuth 2.0 or something else, and who will own and store the credentials.
- What happens when it fails? Is there retrying, logging and an alert so someone knows?
- Who maintains it? Integrations need occasional updates. Agree who watches for version changes.
APIs and your website platform
If your site runs on WordPress, you are already close to APIs. WordPress has long offered an XML-RPC interface, which is what lets mobile apps and desktop blogging tools publish to your site. A community project, the JSON REST API plugin, is working on a modern REST API for WordPress, which would make it easier to use WordPress as a content source for apps and other front ends. WooCommerce added its own REST API in version 2.1 earlier this year, and plugins for Gravity Forms and most email platforms also use APIs behind the scenes.
Custom-built sites and applications can expose their own API, so a mobile app, a partner or an internal tool can read and update data safely without direct database access.
FAQ
Is an API the same as an integration?
Not quite. The API is the doorway a system offers. The integration is the work of connecting two systems through their APIs, including mapping data and handling errors.
Do I need a developer to use an API?
Usually, yes, unless a ready-made plugin or connector already does what you need. Tools such as Zapier can connect many popular services without code for simpler tasks.
Are APIs secure?
They can be very secure when set up properly: encrypted connections (HTTPS), private credentials, limited permissions and logging. Most problems come from careless handling of keys.
How long does an API integration take?
It depends on the systems. A well-documented REST API with a standard task can be quick. Connecting to an older SOAP service or an in-house system with messy data takes longer.
Planning an integration?
If you want your website, accounting, CRM or stock system to share data without manual copying, we can help you plan and build it. See how we approach integrations and custom builds at IWS custom development.
