- What an API actually does
- How requests and responses work
- What JSON and webhooks are for
- API keys versus OAuth
- How a company should manage keys
The short answer
An API is a doorway that a piece of software or a service provides, saying in effect: "If another program asks in this form, I will answer in that form." Instead of a person clicking through screens, programs talk to each other in an agreed format.
When a company starts using APIs, two questions matter more than the technical detail. First, who looks after the API keys and other credentials, and where are they kept? Second, what are the limits on usage and cost? Integrations make work easier, but most of the trouble they cause comes from these two points.
What an API is
Think of a restaurant. An API is the order slip. Customers do not walk into the kitchen and cook; they fill in an order slip in the agreed format and receive their food. They do not need to know how the kitchen works, only how to fill in the slip.
Software works the same way. APIs sit behind integrations such as these:
- An order on an online shop automatically reduces the stock count in the inventory system.
- Payroll software reads the totals from the attendance system.
- A company website shows a map from a mapping service.
- Accounting software pulls in transactions from a bank account.
Each replaces work where a person copied data from one screen and typed it into another. When an AI tool operates another service, it too usually does so through an API.
API stands for application programming interface. "Interface" means a point of contact, so it helps to read it as a doorway meant for programs.
The basics: requests and responses
An API exchange is essentially one round trip: ask, then answer.
- Request: what the caller sends. "Tell me the stock level for this product." "Register this order."
- Response: the service's reply. "Twelve in stock." "Registered." "That product was not found."
A request says where to send it (an address in the form of a URL, called an endpoint), what you want to do (read, create, change or delete) and any data needed. When something fails, the response comes back with a numbered reason such as "not found", "not permitted" or "rate limit exceeded". When an integration stops working, that code and reason is where to start.
REST
A common design approach for web APIs is called REST. We will not go into the formal definition, but in practice it looks like this: the URL identifies the thing, and the type of operation — read, create, change, delete — is sent separately. Send "read" to "/orders/1001" and you get order 1001; send "change" and you update it.
JSON
The data in requests and responses is often written in a format called JSON. JSON lists pairs of a field name and a value, something like {"order_id": 1001, "customer": "Yamada Shoten"}.
Unlike a CSV table, JSON can nest. One order can contain several line items, which is awkward in a flat table but natural in JSON. CSV suits tables that people read and hand over; JSON suits data passed between programs.
Webhooks: being told instead of asking
An API is normally something you ask. To know whether a new order has arrived, you keep asking, "Any new orders?"
A webhook reverses this. You register in advance — "when an order comes in, notify this URL" — and when it happens, the service tells you. An integration such as "post to the team chat when someone submits the contact form" is often built with a webhook.
| What to look at | Asking the API | Webhook |
|---|---|---|
| Who starts the exchange | Your side | The service |
| Best for | Fetching data when you need it | Knowing about events straight away |
| Watch out for | Asking too often hits the rate limit | You need an endpoint to receive it, and it must be protected |
The URL that receives webhooks has to be reachable from outside. Before relying on one, check that the service provides a way to confirm messages really come from it, such as a signature you can verify.
Authentication: API keys and OAuth
Not just anyone can use an API. There are mechanisms to check who you are and what you are allowed to do.
API keys
An API key is a long string issued by the service, sent along with each request. It works much like a password: whoever holds the key can do whatever that key allows. If it leaks, someone else can use the API as you — and if the service charges by usage, the bill comes to you.
OAuth
OAuth lets you allow another app to do a limited set of things without handing over your password. When you start using an app and see a screen asking, "Allow this app to view your calendar?", that is OAuth at work. Your password is never shared; the app receives a permit for the scope you approved, and you can withdraw it later. Strictly speaking, OAuth is about authorisation — what an app may do — rather than proving who you are.
Usage limits and pricing
Most APIs limit how much you can use them: so many calls per minute, so many records per month. Go over and you get errors for a while, or extra charges.
Pricing varies. Some APIs are free up to a certain volume and then charge by usage; some are included in a monthly subscription; some are only available on paid plans. Limits and prices differ by service and change over time, so check each service's official information.
The case to watch for in practice is a bug that sends the same request over and over. The integration can stop when it hits the limit, or, with usage-based pricing, produce an unexpected bill. If the service lets you set a spending cap or an alert, set it before you start.
Using APIs in a company
Once an integration is built it tends to be taken for granted, and who built it is forgotten. Decide these things from the start.
- Decide where keys live. Do not paste API keys into chat, email, shared spreadsheets or directly into program code. Keep them in a password manager or the secret storage the system provides.
- Use separate keys for separate purposes. If one key is shared across several integrations, a leak cannot be traced, and revoking it stops everything.
- Grant only what is needed. An integration that only reads data should get a read-only key.
- Make the company the owner. If contracts and keys are under an employee's personal account, nobody can manage them once that person moves on or leaves.
- Keep a list. Record which services are connected, with which keys, and who is responsible.
- If a key leaks, revoke and replace it. If there is any suspicion a key has leaked, disable it and issue a new one.
Picture a five-person office that paid an outside contractor to connect its online shop to its accounting software. The key exists only in the contractor's notes, and the accounting subscription is in a staff member's personal name. When that staff member leaves, the integration breaks and nobody can fix it. Keeping keys and contracts in the company's name avoids this.
APIs also change at the provider's discretion, and older versions are eventually retired. Assign someone to receive the provider's change notices, so an integration does not simply stop one day without warning.
In short
An API is the doorway through which programs ask and answer in an agreed format. The basic exchange is one request and one response, the data is often JSON, and webhooks let the service notify you instead. Access is checked with API keys or OAuth, and usage and cost have limits. If your company uses APIs, settle where keys are kept, what each key may do, whose name the contracts are in, and keep a list of every integration.