APIs

02How it works

Most APIs on the web work like a very strict form of correspondence. One program sends a request to an address, the other sends an answer back.

• The request names what is wanted, for example "all invoices from October" or "create this customer".
• It carries proof of who is asking, usually a key that the provider issued for this one connection.
• The answer contains the data in an agreed format, today mostly JSON, a plain text format that both sides can read.
• If something is wrong, the answer says so with a defined error, for example that the key is invalid or a required field is missing.

03The documentation is the contract

Every API comes with documentation that lists what can be asked, which fields each request needs and what comes back. This is what makes APIs reliable: both sides agree on the exact shape of every message.

Providers change their APIs over time. Good providers announce changes in advance and keep old versions running for a while, so that connected programs can adapt. When we connect a service, we check how it handles versions and limits before we rely on it.

04A concrete example

Our own operating system, Kadvern One, records the hours we work on each project. At the end of a month the hours for a client have to become an invoice in our bank account at Qonto. Without an API someone would read the hours off one screen and type them into another.

With Qonto's API, Kadvern One creates the invoice draft in Qonto directly, with the right client, items and amounts. One of us checks it there and sends it. The same principle connects Kadvern One to Slack, where it posts notifications, and to GitHub and Vercel, from which it reads code changes and deployments.

05What APIs make possible

Most of what companies ask us to connect falls into a few groups.

• Moving data on its own: new orders, payments or sign-ups arrive in the right system without anyone copying them.
• Reacting to events: when something happens in one system, such as a payment arriving, another system is told immediately. These notifications are often called webhooks.
• Combining sources: a dashboard that shows figures from accounting, sales and a market data provider side by side.
• Using services: maps, address checks, e-mail delivery or AI models are all used through APIs.
• Offering your own: an application can have its own API, so that partners or your other systems can use its data in a controlled way.

06Alternatives and how they compare

Exports and imports, such as a CSV file downloaded from one tool and uploaded to another, work without any programming. They depend on someone remembering to do it, and the data is out of date the moment the file is saved.

Automation platforms connect popular services through ready-made building blocks. They are quick to set up for simple flows and cost a monthly fee per volume of tasks. Underneath, they also use the APIs of the services involved. A direct connection is worth it when the flow has many rules, handles a lot of data or carries information that should not pass through another provider.

07What to watch out for

• Not every tool has an API, and some only offer it in more expensive plans. Check this before choosing a tool you want to connect.
• Many APIs limit how many requests are allowed per minute or day. A connection has to respect these limits.
• Some data providers charge per request or restrict how their data may be used and shown. Read the licence terms, especially for market and company data.
• API keys are like passwords. They belong in a secure store on the server, never in an e-mail or in the code.
• A connection needs monitoring. If the other side is down or changes something, someone should notice before the data is missing.

08How we use them

Kadvern One creates quote and invoice drafts in Qonto, posts notifications to Slack and reads repositories and deployments from GitHub and Vercel, all through their APIs. In client projects we connect data providers, document stores and the tools the client already works with.

Keys are stored encrypted or as protected settings with the hosting provider, never in the code. Where an application holds keys for a client's own services, those keys belong to the client's accounts.

Frequently asked questions