APIs explained for business people: REST, webhooks and rate limits

Almost every modern business runs on software talking to other software. Your shop sends orders to your accounting tool. Your payment provider tells your app that a card was charged. Your CRM pulls in leads from a form. The connections that make this happen are APIs, and the words around them (REST, endpoints, webhooks, rate limits) turn up in every integration quote and every incident report.

This guide explains those terms for people who commission, buy or manage integrations rather than write them. By the end you should be able to read an integration plan and ask the questions that prevent most problems.

What an API is

An API (application programming interface) is a published way for one piece of software to ask another for data or to make it do something. Think of it as a service counter with a written menu. You can’t walk into the kitchen, but you can order anything on the menu, in the format the menu describes, and you get a predictable reply.

Most business APIs run over the same HTTP protocol your browser uses. A program sends a request to a web address, called an endpoint, and gets back a response, usually in a text format called JSON. Access is controlled with keys or tokens, which work like passwords for software. Anyone holding your API key can act as your business, so keys should be stored securely and never pasted into emails or chat.

REST in plain English

You will often hear “REST API” or “RESTful”. MDN’s glossary entry on REST defines it as “a group of software architecture design constraints that bring about efficient, reliable and scalable distributed systems”. It adds a useful simplification: HTTP APIs are often called RESTful even when they don’t follow every constraint, and “beginners can assume a REST API means an HTTP service that can be called using standard web libraries and tools”.

In practice a REST-style API is organised around things, called resources, such as customers, orders or invoices. Each has an address, and the HTTP method says what you want to do with it:

The API’s documentation lists which resources exist, which fields each one has and which methods are allowed. When a developer says “the API doesn’t expose that”, they mean the field or action you want isn’t on the menu, and no amount of effort on your side will add it.

Webhooks: being told instead of asking

A normal API call is a pull: your system asks “has anything changed?” A webhook is a push: the other system calls you when something happens. Instead of your app checking every few minutes whether a payment went through, the payment provider sends a message to an address you give it the moment it does.

Stripe’s webhook documentation is a clear model of how this works and what can go wrong. It describes webhooks as a way to respond to events such as “when a customer’s bank confirms a payment, a customer disputes a charge, or a recurring payment succeeds”. Several of its rules apply to webhooks from any provider:

• Verify the sender. Stripe signs each event and warns that without verification “an attacker could send fake webhook events to your endpoint to trigger actions like fulfilling orders”.
• Reply fast. The receiving endpoint must “quickly return a successful status code (2xx) before any complex logic that might cause a timeout”, and do the heavy work afterwards.
• Expect retries. In live mode Stripe retries failed deliveries “for up to three days with an exponential back off”.
• Expect duplicates. Endpoints “might occasionally receive the same event more than once”, so your system should record event IDs and skip ones it has already processed.
• Don’t rely on order. Stripe “doesn’t guarantee the delivery of events in the order that they’re generated”.

Those last two points cause many real-world bugs. If your system sends a welcome email every time it receives a “subscription created” event, a duplicate delivery means a duplicate email. If it expects “invoice created” before “invoice paid”, an out-of-order delivery can confuse it.

Rate limits: the speed limit on the counter

APIs limit how many requests a client can make in a period, to protect the service and share capacity fairly. MDN describes the 429 Too Many Requests status code as the server saying “the client has sent too many requests in a given amount of time”, and notes that a Retry-After header may say how long to wait.

GitHub’s documentation on its REST API rate limits shows what these limits look like. Unauthenticated requests are limited to 60 per hour, while authenticated users get 5,000 per hour. Each response carries headers showing how many requests remain and when the window resets. When a client hits the limit, GitHub says it “should not retry” until the reset time, and that continuing to send requests while limited “may get your integration banned”. For repeated failures it recommends waiting longer between each retry.

Rate limits matter to business owners because they set the ceiling on bulk jobs. Syncing 50,000 products to a marketplace through an API limited to a few requests per second will take hours, not minutes, and the plan should say so.

A worked example

An example (illustration only). A subscription coffee business wants paid orders from its payment provider to appear in its warehouse system and its accounting software.

1. The payment provider sends a “payment succeeded” webhook to the business’s integration service.
2. The service checks the signature, stores the event ID and replies 200 straight away.
3. A background job uses the warehouse API (POST to create a shipment) and the accounting API (POST to create an invoice).
4. If the accounting API replies 429, the job waits for the time in Retry-After and tries again.
5. If the same event arrives twice, the stored ID means the second copy is ignored, so no double shipment goes out.

Each step maps to a question the owner can ask the developer: how do we verify webhooks, how do we handle duplicates, what happens when a partner API is slow or limits us, and who gets alerted when something fails?

Common mistakes

• Assuming the API can do everything the app’s screen can. Many features in a product’s interface are not available through its API. Check the documentation before promising a feature.
• Sharing API keys loosely. Keys sent by email or committed to code can be copied. Store them in a secrets manager and rotate them if exposed.
• Processing webhooks without signature checks, which lets anyone fake events.
• Ignoring duplicates and ordering, which leads to double emails, double shipments or wrong statuses.
• No monitoring. Integrations fail silently. Someone should be alerted when webhooks start failing or a sync stops.
• Forgetting rate limits when planning migrations and bulk imports.

When to use an API, a webhook or neither

Use an API call when your system needs to fetch or change data on demand, such as looking up stock levels when a customer opens a page. Use a webhook when you need to react to events in another system quickly, such as payments, refunds or form submissions. Many integrations use both: a webhook says something happened, then an API call fetches the full details.

Neither is worth building for a task that happens once a month and takes five minutes by hand. A CSV export and import, or an off-the-shelf connector from an automation service, may be enough until the volume justifies custom work.