API — what is it? REST API, webhooks and OpenAPI explained for business

"We have an API for that" — it's a sentence anyone who talks to developers or a software vendor eventually hears. What is an API? In short: an API (application programming interface) is an agreed way for one program to ask another for data or for an action — without a person involved, without clicking through screens, and without copying data from one window into another.

This article is for business owners and managers who want to understand what their developers are talking about, well enough to ask the right questions. We start with real-world examples, then move to the terms that come up in every conversation about integration: REST API, webhook, OpenAPI, API key. Every definition links to the source that defines it — documentation, a specification, or a standard.

API — what it is, with real-world examples

The easiest way to understand an API is through three services many Swiss businesses use, often without realising it happens through an API.

A reference exchange rate from the Swiss National Bank. A finance system that enters a EUR/CHF exchange rate into an invoice doesn't open the SNB's website. It sends a request to the SNB data portal API, which publishes monthly average and end-of-month exchange rates, among other statistical series, through a public web service.

Validating a company's UID number. Before taking on a new supplier or customer, a business can automatically check that the company is registered under the business identification number (UID) it gave. The Federal Statistical Office provides the UID register's public services for this — a web service with operations including GetByUID, Search, ValidateUID and ValidateVatNumber. Unlike the other examples here, this one is a SOAP service, not REST — a good real-world case for the SOAP section below.

Looking up a registered business. The Zefix PublicREST API, the federal commercial-register index, publishes an OpenAPI 3.1.0 specification and requires HTTP Basic credentials to call — a good real example for both the OpenAPI and the API-key sections further down.

In all three cases the pattern is the same: one program (the client) sends a request in an agreed format, and another (the server) sends back a response, also in an agreed format. That agreement — what requests you can send, what data they need, and what comes back — is exactly what an API is.

Here's what this looks like in practice. Below is a request for the EUR/CHF monthly average exchange rate, made on 2 October 2026 against the SNB data portal, and the server's response:

1GET https://data.snb.ch/api/cube/devkum/data/json/en?dimSel=D0(M0),D1(EUR1)&fromDate=2026-09
Copy

1{"timeseries":[{"header":[{"dim":"Monthly average/End of month","dimItem":"Monthly average"},{"dim":"Currency","dimItem":"Europe - EUR 1"}],"metadata":{"key":"[email protected]{M0,EUR1}","frequency":"P1M","scale":"","unit":"Rates at 11 am. in CHF"},"values":[{"date":"2026-09","value":0.94312}]}]}
Copy

You don't need to know how to program to read this: 1 euro is worth 0.94312 Swiss francs, as a monthly average for September 2026. A finance system does exactly the same thing, just inserting the number into the right field itself. (The call above worked without registration or a key; check the SNB's terms of use before you build on it.)

REST API — what it is and where it comes from

When a developer says "we have a REST API", they mean an API built according to a particular architectural style. The term REST (Representational State Transfer) was introduced by Roy Fielding in his 2000 doctoral dissertation. In chapter 5 he builds it up step by step, adding constraints to a system that starts out with none.

Fielding's six REST constraints

1. Client–server. The client (the application asking for data) and the server (the system storing it) are separated and can evolve independently.
2. Statelessness. Fielding writes: "each request from client to server must contain all of the information necessary to understand the request, and cannot take advantage of any stored context on the server." That's why every API request sends something like a key along with it — the server doesn't "remember" who asked a minute earlier.
3. Cache. Responses can be marked as safe to store and reuse, saving future requests.
4. Uniform interface. This is the heart of REST. Fielding: "REST is defined by four interface constraints: identification of resources; manipulation of resources through representations; self-descriptive messages; and, hypermedia as the engine of application state." In practice: every resource (an invoice, a shipment, a link) has its own address, and operations on it use the same standard methods.
5. Layered system. Intermediaries — caching servers, security layers — can sit between client and server without the client needing to know about them.
6. Code on demand. The server can send the client code to execute. This is the only optional constraint — Fielding notes that it reduces visibility, "and thus is only an optional constraint within REST."

RESTful API — what that means

"RESTful API" simply means an API that follows these rules. In everyday use, REST API and RESTful API mean the same thing: an API over HTTP where resources have addresses and operations use standard HTTP methods. Many APIs called "REST" don't satisfy all six constraints to the letter — especially the hypermedia one. For a business using them, that usually doesn't matter; what matters is whether the API is well documented and predictable.

HTTP methods and idempotency

In a REST API, the HTTP method tells the server what to do with a resource. Method semantics are set by the HTTP standard, today RFC 9110:

• GET — fetch: "requests transfer of a current selected representation for the target resource";
• POST — process the submitted data according to the resource's own semantics; in practice, most often: create a new record;
• PUT — create or replace a resource with the state sent in the request;
• DELETE — remove the association between a resource and its prior function — in practice: delete.

For a business, the single most important concept from this standard is idempotency. RFC 9110 defines it this way: a method is idempotent "if the intended effect on the server of multiple identical requests with that method is the same as the effect for a single such request." GET, PUT, DELETE and other safe (read-only) methods are idempotent. POST is not.

Why does this matter? Because connections drop. The standard explains that an idempotent request can be safely retried automatically if communication breaks before the client reads the response. Sending "delete invoice no. 15" twice gives the same result as sending it once. Sending "create a payment" twice can create two payments. That's why payment integrations need explicit protection against duplicates — our own web-app cost calculator says exactly that about this line item: payment integration "requires webhook handling, idempotency logic, and compliance testing — not just embedding a checkout widget."

SOAP vs REST

Older systems — banking, government, enterprise — often expose an API in a different standard: SOAP. Per the W3C's SOAP 1.2 specification (a Recommendation since 27 April 2007), it is "a lightweight protocol intended for exchanging structured information in a decentralized, distributed environment," built on XML technologies. Switzerland's own UID register, described above, is a current, real-world example: it's a SOAP service with operations like GetByUID and ValidateVatNumber, not a REST API.

The practical difference, from a business perspective, isn't ideological. SOAP is a protocol with its own tightly defined XML message envelope. REST is an architectural style that uses what HTTP already gives you — addresses, methods and status codes — usually carrying data as JSON. If a provider only offers SOAP, integration is entirely possible — it just needs different tooling and usually more work handling the messages. We won't cite statistics on which standard is "more popular", because we didn't find any we'd stand behind.

Webhook — what it is and how it differs from calling an API

A plain API works on "ask, and you'll get an answer". If you want to know whether a customer has paid, you have to keep asking. A webhook flips that direction: the system where something happened sends a message, on its own, to an address you've told it to use.

GitHub explains this as simply as possible in its webhook documentation: webhooks let you "receive data as it happens, as opposed to polling an API (calling an API intermittently) to see if data is available." Stripe, the payments operator, writes that once you register a receiving endpoint, "Stripe pushes real-time data to it when events happen in your Stripe account," as JSON over HTTPS.

In practice, the two approaches complement each other. A webhook is better when response time matters — a payment, a new order, a shipment-status change. Polling is good enough when data changes rarely, or when a provider simply doesn't offer webhooks at all. Stripe gives recipients one important piece of advice: an endpoint receiving webhooks should return a success code (2xx) quickly, before running any complex logic that could cause a timeout.

Verifying a webhook's signature

The address that receives webhooks is public — anyone can send anything to it, including a fake "order paid" message. That's why serious providers sign every message, and the recipient has to verify that signature.

• Stripe puts the signature in the Stripe-Signature header, generated as an HMAC with SHA-256, using a secret tied to that receiving endpoint. A timestamp is signed together with the message body. The timestamp protects against replaying an intercepted, old message: Stripe's libraries use a default tolerance of 5 minutes between the timestamp and the current time (Stripe, webhooks).
• GitHub sends its signature in the X-Hub-Signature-256 header, always prefixed with sha256=. The documentation warns against comparing signatures with a plain == operator, and instead to use a constant-time comparison function — one that can't be guessed by timing the response (GitHub, validating webhook deliveries).

HMAC is a signature created with a shared secret: only the sender and the recipient know it, so only they can generate and verify a correct signature. For a business owner, the takeaway is simple: when asking an integration provider about webhooks, also ask whether messages are signed, and whether your system checks that signature.

OpenAPI — what it is, and why a business needs API documentation

An API without documentation is like a contract nobody wrote down. OpenAPI is the standard for writing that contract down. The current version of the specification is OpenAPI Specification 3.2.1, published on 10 September 2026. Its opening sentence explains what it's for: "The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic."

In practice, an OpenAPI file lists every API address, method, required field, possible response and authentication method. Tools can generate readable, browsable documentation straight from that file, letting a developer send a test request immediately. The Zefix PublicREST API, mentioned above, is a good local example: its published OpenAPI 3.1.0 specification lists endpoints such as company search and lookups by UID, together with the HTTP Basic credentials a caller needs.

Why does this matter to a business, not just to developers?

• Changing contractors doesn't start from zero. If your system's API is described in OpenAPI, a new team knows what it does without reading the whole codebase.
• Partners can integrate themselves. Instead of explaining to every partner by e-mail how to submit an order, you give them a link to the documentation.
• It's easier to verify what was actually delivered. The specification is a concrete deliverable you can accept alongside the application itself.

That's why, in our own calculator, the "public API / integrations" line item is described, in its own words, as covering "API keys, rate limiting and OpenAPI docs" — not just the underlying code.

API keys and integration security

API keys, Bearer tokens and rate limits

An API key is a long, random string that identifies the program sending requests and grants it access. It's most often passed in the Authorization header as a so-called Bearer token — "the bearer": whoever holds it has access. Some providers instead require HTTP Basic credentials, as the Zefix PublicREST API does. Three practical rules apply either way. Credentials stay on the server only, never in code visible in a browser and never in an e-mail. Every integration should have its own credentials, so a leak lets you revoke one set instead of all of them. Credentials are worth rotating periodically.

Some providers use the OAuth standard instead, where an application gets a token on behalf of a specific account.

The second element is rate limiting. A provider caps how many requests you can send in a given time, so one client can't overload the service. A well-designed API tells you about this in its responses — for example, headers showing the limit, how many requests remain, and when the limit resets. Your integration has to respect those limits: spread requests out over time, and not retry in a tight loop after being refused.

OWASP API Security Top 10 2023

OWASP, the application-security organisation, publishes its own top ten list of API risks. The 2023 edition looks like this (titles as published, explanations ours):

1. API1:2023 – Broken Object Level Authorization — the API doesn't check whether the requester is allowed to access a specific record; changing an invoice number in the address shows someone else's invoice.
2. API2:2023 – Broken Authentication — flawed login, key or token handling.
3. API3:2023 – Broken Object Property Level Authorization — no control over individual fields: the API returns or allows changes to fields a user shouldn't be able to see or edit.
4. API4:2023 – Unrestricted Resource Consumption — no limits on requests or resources, risking overload or runaway bills.
5. API5:2023 – Broken Function Level Authorization — an ordinary user can call functions meant for an administrator.
6. API6:2023 – Unrestricted Access to Sensitive Business Flows — business processes (purchases, bookings, sign-ups) can be automated at scale, to the business's detriment.
7. API7:2023 – Server Side Request Forgery — the API fetches a resource from an address supplied by the user, and can be tricked into requesting places it shouldn't reach.
8. API8:2023 – Security Misconfiguration — configuration mistakes: unnecessary features left on, missing updates, overly detailed error messages.
9. API9:2023 – Improper Inventory Management — a company doesn't know which API versions and endpoints it has exposed; old, forgotten versions stay open.
10. API10:2023 – Unsafe Consumption of APIs — excessive trust in data from other people's APIs, without validating it.

That last point applies to any business that merely uses other people's APIs: external data has to be checked too. How responsibility for security is actually split when data sits with an external provider is covered in our article on cloud data security.

Public APIs you'll run into in Switzerland

Many integrations at Swiss businesses touch the same few public services. Below is a short list with links to the official documentation.

• SNB data portal API — publishes exchange rates and other statistical series from the Swiss National Bank as a public web service (data.snb.ch).
• UID register — public services — a SOAP web service from the Federal Statistical Office for looking up and validating a company's UID, including a VAT-number validation operation (uid-wse.admin.ch).
• Zefix PublicREST API — the federal commercial-register index, published as an OpenAPI 3.1.0 specification, requiring HTTP Basic credentials to call (zefix.admin.ch).
• QR-bill — the Swiss invoicing data standard, carrying all the information needed for a payment in a machine-readable format; worth knowing about alongside any of the APIs above.

An example from our own site: how we use the DVN Links API

The most honest integration example we can show is our own. DVN Links is our own product — the EN site describes it as "a European link management platform with analytics and QR codes". The site you're reading uses its public REST API every time an article or page is published — the same API that paying-plan customers get (per its pricing page, API access starts from the Starter plan).

What our site actually does, in plain terms:

1. Creates a short link on publication. If a document doesn't have a short link yet, the site sends a POST /links request with the target address and stores the resulting short link and link ID on the document.
2. Checks the link on later publications. If an ID already exists, the site asks GET /links/{id} whether the link still exists and where it points.
3. Recreates a link if someone deleted it in the DVN Links panel — it simply creates a new one.
4. Updates the target when an address changes. When an article's address changes, the site sends PATCH /links/{id} with the new target. The old short link keeps working and now points to the new address.
5. Adopts old links. Documents that had a short link saved before this integration existed, but no ID, are matched by searching for the exact target address, and the found link is adopted instead of a duplicate being created.

Two design decisions matter here more than the requests themselves. First, the integration never blocks publishing — if DVN Links doesn't respond, the article publishes anyway, and the error only goes to the logs. Second, without a configured API key, the integration simply does nothing. You can also see the idempotency point from earlier in practice: POST creates a new resource, so before calling it, the site always checks whether a link already exists.

DVN Links' own API has features worth asking any provider about. It's described by an OpenAPI 3.1.0 specification, from which browsable documentation is generated. Every request requires a key passed as a Bearer token in the Authorization header. Rate limits depend on the plan, and every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.

DVN Links has no webhooks. That makes it an example of polling: our site checks a link's state itself, when it needs to, instead of waiting for a notification. For this use case that's enough, since we only need to check a link at the moment of publishing.

Integrating via an API instead of copying data — when it pays off

Every API integration replaces work someone at the company currently does by hand: copying orders from a platform into a warehouse system, pasting an exchange rate into an invoice, checking a trading partner before a transfer. The question isn't "should we integrate", but "which manual copying is actually costing us the most".

Integrating via an API usually makes sense when:

• the same action repeats often — daily, or on every order, not once a quarter;
• a mistake is costly — a wrong account number, an incorrect invoice amount, a shipment that never goes out;
• response time matters — a customer is waiting for payment confirmation or a shipment number;
• both sides have documented APIs — ideally in OpenAPI, or at least with full documentation and a test environment.

Integration doesn't make sense when the action happens rarely, or when a provider has no API, or changes it without notice. In that case, maintaining the integration ends up costing more than doing the work by hand.

The cost of an integration itself depends on its scope — we scope and quote every integration individually, because it depends heavily on the quality of the API on the other side. Our web-app cost calculator gives a rough starting point for the two most common line items: public API integrations, and online-payment integration.

Once several integrations exist and start forming a chain — an order, an invoice, a shipping label, a customer notification — that's already process automation, not a single connection. We cover that in our article on business process automation, and our approach is described on our process automation page. If integrations are meant to be part of a new system, start with our article on what a web application is and our web application development offering. When off-the-shelf tools with built-in integrations aren't enough, there's custom software. We've collected our other articles on web applications in our guide to web applications.