An API is an agreed way for one program to ask another to do something or hand over data: your website asks the payment service “has this order been paid?” and gets an answer in a machine-readable format. A business needs APIs so its systems — website, 1C, CRM, marketplace, messengers — exchange data on their own, without manual copying. Before an integration, find out where the access keys are stored, what happens when something fails and who watches the limits.
After this you will be able to
- Explain what an API, an endpoint, a method and a response code are, using a restaurant and online payments as examples
- List the rules for handling API keys and tokens: where to store them, whom not to share them with, when to rotate them
- Tell an API request from a webhook and explain what a 429 Too Many Requests response means
- Ask a contractor the right questions before an integration using a seven-point checklist
Contents
An API is the menu and the waiter between programs
Let’s go back to the restaurant from the article on how a website works. A guest doesn’t walk into the kitchen and grab ingredients: they open the menu, choose a dish and give the order to a waiter. The menu is the API documentation: a list of what can be ordered and in what form. The waiter is the API itself: it takes the order by the rules, carries it to the kitchen and brings back the result. The kitchen is someone else’s system, and you don’t need to know how it works inside.
The abbreviation stands for Application Programming Interface. As MDN explains, it is a set of features and rules through which one program uses the capabilities of another. If a website’s interface is made for people, an API is an interface made for programs.
Request and response: how programs talk
Most web APIs run on top of the same HTTP protocol the browser uses to fetch pages. The conversation always consists of a request and a response. Here is what a single request is made of:
Address — the endpoint
A specific address responsible for one action: for example, one address for orders and another for products. An endpoint is a line on the menu.
Method
The verb of the request: get data, create a record, change it or delete it. The standard HTTP methods are described in the MDN documentation.
Access key
Proof that the request was sent by your system and not by a stranger.
Data
What exactly you pass on: an order number, a customer’s phone, the contents of a cart.
Response with a code
The system returns a result and a numeric code: success, record not found, no access, or too many requests.
GET
- What it does
- Retrieve data
- Business example
- Check a product’s stock in the warehouse
POST
- What it does
- Create a new record
- Business example
- Send a request from the website to the CRM
PUT / PATCH
- What it does
- Change an existing record
- Business example
- Set an order’s status to “shipped”
DELETE
- What it does
- Delete a record
- Business example
- Remove a cancelled booking
Data is most often sent as JSON — a simple text format defined in the IETF standard RFC 8259 and easy to read for both programs and people. A response about an order might look like this: {"order": 1042, "status": "paid"}. These are “name — value” pairs, like lines on a form.
Keys and tokens: how another system recognises you
To answer, the system has to understand who is asking and what they are allowed to do. For that, when you connect you receive an API key or token — a long string of characters that your server attaches to every request. It works like an employee pass: security doesn’t know your face, but sees a valid pass.
Many APIs use so-called bearer tokens. The RFC 6750 standard warns plainly that any party in possession of such a token can use it. That’s why keys are handled like bank passwords.
- Keys are kept only on the server — in the frontend any visitor can see them
- Keys are never sent through messengers or pasted into shared documents
- Each integration gets its own key with the minimum rights it needs
- Keys are issued in the service’s account registered to the company
- When a contractor or employee leaves, the keys are reissued
Asking or being notified: REST and webhooks
The most common style of web API is called REST: data is represented as resources with their own addresses, and actions on them use the standard HTTP methods. With REST, you take the initiative: your system comes and asks. A webhook works the other way round — the other system sends a message to your address when something has happened.
Request (you ask)
- Your server calls the service when it needs data
- Good for lookups: stock, exchange rates, status on demand
- Ask too often and you may hit a limit
- Ask too rarely and the data lags behind
Webhook (you are told)
- The service sends a notification to your address on its own
- Good for events: a payment went through, an order arrived
- Your server must be reachable and able to verify the message is genuine
- You need a plan for when a notification gets lost
Most services have limits — how many requests you can send per minute or per day. When you exceed them, the server answers with 429 Too Many Requests: this code is defined in RFC 6585, and MDN calls the mechanism rate limiting. A good integration knows how to wait and retry instead of losing data.
Where businesses meet APIs
Online payment
- What the API does
- Creates a payment and reports the result
- What to watch for
- Confirm payment via webhook and a server-side check, not by the customer returning to the site
1C accounting
- What the API does
- Moves orders, stock and prices between the website and accounting
- What to watch for
- Which system is the source of truth for each field and how often data is exchanged
A marketplace such as Kaspi
- What the API does
- Pulls orders and updates prices and availability
- What to watch for
- The specific platform’s rules and limits according to its documentation
Maps and addresses
- What the API does
- Suggests addresses, calculates distance for delivery
- What to watch for
- Free usage limits and the service’s terms
Messengers
- What the API does
- Sends notifications, receives messages from a bot
- What to watch for
- Whose account the bot belongs to and who holds its token
CRM
- What the API does
- Creates a deal from a website request
- What to watch for
- What happens to the request if the CRM is temporarily down
We have written separately about the two most common integrations in Kazakhstan — integrating with Kaspi and connecting 1C to a web application. The principle is the same everywhere: first agree which system is the master for each type of data, and only then build the exchange.
What to ask a contractor before an integration
- Does the service have official API documentation, and which version will you use
- Where will the keys and tokens be stored, and whose name is the service account in
- How will the integration behave if the other service is down or returns an error
- How are request limits handled and what happens if they are exceeded
- How are incoming webhooks verified as genuine
- Where are exchange errors logged, and who gets notified of a failure
- What needs to change if the service releases a new API version
A good integration is invisible while it works and speaks up loudly when something goes wrong. A bad one does the opposite.
