An API is a written agreement one program gives another: ask this address with these names and you get this back. Whether a business needs one is settled by which program outside your own application touches the same record, not by a choice of technology. At Tahlil.com the app on a patient’s phone runs apart from the website where the values go in, yet it reads the same record.
What an API is, what the letters stand for, and what it is for
The letters stand for application programming interface. The word interface is what trips people up, because in everyday use it means a screen. This one has no picture. A person using the software sees buttons and tables; the API carries the conversation happening behind them, and nobody watching the screen sees any of it.
What gets written down is short and specific. There is an address the question goes to. There is a set of field names to use when asking. There is a shape the answer arrives in. Fix those in advance and the calling side can ask the same way every time and know what it will get.
That is also why an API has no human user. Nobody opens one and looks around inside. The party using it is another piece of software, written either by you or by somebody else. For a business owner the practical consequence is worth holding onto: a request for an API is not a request for a screen, and its scope is measured in programs attached to a record rather than in pages.
The agreement earns its keep in what it removes. Without something written down, two separately running programs sharing a record have to be revised together every time either one moves. With it, one side can be rebuilt internally and the other side never hears about it. The only event that obliges a conversation is a change to the agreement itself.
There is a second thing it buys you. Adding a surface to a record does not mean rewriting the agreement; the new arrival asks the same gate using the same names. Without one, every new surface would cut its own path into the record, and nobody could say which of those paths returned the right answer.
One boundary before we go on. The same abbreviation names other things in medicine and in aviation, and those meanings have nothing to do with this one. What follows is the software sense: the agreement between programs.
What travels in a call, and what comes back
In its shortest form the mechanism goes like this. The calling program goes to a fixed address, fills in named fields and leaves a request. The far side picks the request up, does whatever its own work involves, and hands back an answer under the same names. Because both the outgoing and the incoming names were written down first, neither side has to guess.
The real payoff follows immediately. The caller does not have to know how the far side works. All it knows is which name to ask under and what it will get. Rebuild the work behind the gate from scratch and the calling program stays untouched, so long as the names and the shape of the answer hold. Translated into business terms: an improvement made on one side does not turn into a line item on the other.
Who starts the call is part of the agreement too. One side holds a gate open and waits; the other side is the program that knocks. The waiting side never speaks first, and it stays silent until asked. That distinction is useful when you are scoping work, because it says which half is being commissioned. Are you having the gate built, or the program that knocks on somebody else’s gate?
If your quote says REST API, you are not looking at a second item. REST is the name of one way of writing this agreement down: how the address is formed, how the request is sent, how the answer is arranged. The gate is still an API. What the word adds is the convention it follows. Two lines in a quote that look like two purchases are often the name of a thing and the manner of writing it.
API integration is not a separate technology either. It is the everyday word for joining two programs through this gate. The substance of the request has nothing to do with tooling and everything to do with records: which record opens to which program, who starts the call, which fields cross. Answer those and scope and price become discussable; leave them open and the request has no description to price. How any particular outside system gets connected is its own subject, and when the ledger belongs to somebody else we covered the shape of that work in the piece on handing records to a bookkeeping program.
There is also the case where no gate gets built at all. With no second program running apart from yours, no calls travel between them, and no agreed list of names comes into existence. That case has its own evidence at the end of this article.
What forces the gate open is a second program touching the record
The question usually gets asked from the wrong direction. How many screens will we have tells you nothing about whether you need an API. The question that does tell you is this one: which program, running outside my own application, is going to touch this record? You can answer it without knowing a single technical term, because the answer lives in how the work happens rather than in the software.
Try it on your own operation. Name the record first: customer, device, order, appointment. Then list the programs that arrive alongside it. Office staff work through a panel, which is one program. A crew in the field arrives with a second one. An outside service brings its own. If any line on that list runs outside your application, a gate has entered the conversation.
The platform where a patient’s own test values pass under physician review shows the mechanism plainly. Values go in through the website, the interpretation is written and approved in the physician panel, and the app on the phone is another arrival that runs somewhere else entirely. All of them look at one record. The phone, though, is not hardware the business operates; it belongs to a patient, who also decides when the app opens at all.
Our own product, where the office’s customer and device records meet the technician in the field, draws the same line between office and site. The field app rides in a technician’s pocket while the office works from a browser. Neither keeps its own ledger. A job the technician opens in a boiler room lands on the record the office is already reading.
In both cases ownership is not what forces the gate. The program on the phone may be ours; the whole product may be ours. What forces it is that the program runs somewhere else, on its own. Two separately running parties meeting over one shared record need something written between them, and without it every release means changing both at once.
That gives us a boundary. Which device the app opens on, whether it goes to a store, and what happens when the connection drops are not this article’s decisions. They are settled on the mobile app side. What is settled here is the gate itself.
The opposite case deserves saying out loud. If one program touches the record, a gate is a cost with nothing behind it. How many surfaces end up reading one core, and when that question has to be closed, is a different argument; we made it in the piece on decisions that are expensive to reverse.
The gate carries traffic inward as well as outward
The word gate suggests a one-way pipe, with records inside being handed out. Traffic actually runs in both directions, and no second gate gets built to carry the return leg.
In AlgoKlima the most ordinary version of this is job assignment. Which job goes to which technician is decided on the office side and written onto the same customer and device record. The field app reads that assignment from the record. So the first thing crossing the gate is not data coming up from the field; it is work going down to it.
On the ground that has a concrete shape. A technician does not phone the office to find out what the morning holds; the app reads the assignment off the record and shows it. The office hands work over by editing that same record. Keep the assignment in a separate messaging channel instead and the record itself would not carry who it belongs to, leaving the two sides free to read different things.
The return leg lands in the same place. The technician opens a service record, writes what was done and closes it, and what gets written is the record the office is reading. Because warranty and maintenance history accumulate under the device, files for units sitting at one address do not get mixed up. Both directions meet over a single record, and no second copy is held in between.
Staying on one record has a price as well as a payoff. Keep separate copies and you would later have to write the rule that decides which copy wins. One record never raises that question. What it raises instead is the question of the same record being edited from two places, and that question goes into the design of the gate.
At Tahlil.com one record is written through one surface and read through another. The value arrives from the website, the physician panel is where the interpretation gets written and signed off, and the app on the phone alerts the patient once that text is ready and reads it from the same record. Hold a separate copy and nobody could promise that the interpretation approved in the panel is the interpretation the patient sees.
One thing this section deliberately leaves alone. Holding a record on the phone with no connection, queueing it until the signal returns and merging edits that collide is a mechanism of its own, and we set it out in the article on where a field record is created. Here the subject is the gate: one record, reached from both directions through the same opening.
Whose side is the far side of the gate
Underneath the vocabulary, the owner’s real question is about control. Am I the one holding the gate open, or am I passing through somebody else’s? The two situations are not the same, and what you can change afterwards differs in each.
Both sit under one roof in our work. In the tool that reads marks straight off the image of an answer sheet, the reading service is on our own side. It sits in its own runtime, the call goes out from us, and the result is written into the platform’s exam record. Because we write both sides of that gate, a rename is a single decision taken at one table.
In the tool that cuts a printed booklet into individual questions, the situation inverts. Tying an answer to its question comes back through an outside model provider’s gate. There we are not the ones holding a gate open; we are the ones knocking. The names and the shape of the answer are set on the far side, and our work is fitting what comes back into our own record layout. Two opposite arrangements under one roof make the distinction a fact about the work rather than a preference.
Who owns the far side sets what you can change at the gate. The rows below put the gate side of each job in this article next to each other.
| The program on the far side of the gate | Whose side it is | Who does the work when names change |
|---|---|---|
| The app on a patient’s phone, looking at the same record as the site that takes the values | The platform’s own side; both ends of the gate live inside it | A rename is planned across the platform’s surfaces together |
| The field app on a technician’s phone, working on a single customer and device record with the office panel | Ours; our own product, and we write both surfaces | Us; because the two sides run in separate places, a change is planned on both at once |
| Our own reading service, sitting in its own runtime and writing results into the exam record | Ours; we build the service and the record | Us; a change in form layout is absorbed inside the service |
| An outside model provider’s gate, returning the work of tying an answer to its question | Someone else’s; we do not hold the gate, we knock on it | Us; the far side sets the name and the timing, and the adapting happens on our side |
| No second program; panel and visitor page in one application, and we are building the product now | No gate is built; no separate API layer opens | The question does not arise; there is no agreed list of names between two programs |
Even when the far side is yours, the gate is not free. Because the two halves run in separate places, a rename has to be planned on both at the same time; update one and leave the other asking under the old name, and the call finds nothing. Owning both sides makes the work easier rather than unnecessary, because both ends of the gate still have to move together.
Once the names pass through the gate they stop being yours alone
Business owners tend to file renaming under later. Once a field name has passed through the gate, later stops being available on its own. The name is no longer only your call; it has become an obligation two programs share.
The optical-mark side shows this working. When a new sheet layout reaches the institution, the adaptation is carried out on the reading service’s side. The record layout on the far side of the gate is left alone; the exam record stays where it is and the result still lands there under the same names. That is where the gate pays for itself. One side moves and the other side does not have to.
The cropping side is the same mechanism seen from behind. There the names and the shape of the answer are set by the far side, not by us. When the far side renames something, the adaptation falls to us and we do not set the schedule either. Which side of the gate you stand on decides who carries the fitting work.
The difference in schedule matters more than it sounds. With both sides in our hands, a rename travels inside one plan. With the far side belonging to somebody else, both the timing and the content of the change are theirs, and our work is absorbing it when word arrives. The same task answering to two calendars changes the price side of the gate decision as well.
From all of this comes a rule a reader can use. Renaming a field inside one application is an edit. Put a separately running program behind it and the same rename becomes a piece of fitting work. So we treat the list of field names as a promise given rather than as internal housekeeping. Narrowing which fields cross the gate at the outset also narrows how many future changes turn into fitting work.
The limit is worth stating. Holding the names steady does not freeze the work behind the gate. The inside of the reading service can change as much as it likes; what cannot move is the promise it makes outward. Without that separation, every improvement would turn into a negotiation.
The job with no gate: when both halves live in one application
Choosing not to build a gate is also a decision. We are building our own card product, where a printed code keeps its address while the page behind it is edited from a panel, and there the management panel and the visitor’s page sit inside one application. No API layer comes between them. The reasoning behind that choice lives in the piece on moving printed menus and catalogues into software; here it stands as a fact and nothing more.
The mechanism proves the argument from the other end. What creates a gate is a separately running program reaching the record, not a technology choice. With no such program, there is no list of names to agree on. The panel updates a record and the visitor’s page reads it from inside the same application, so no point arises where two parties owe each other a promise. Not building the gate is a scope decision, not an omission.
We are not claiming the decision is permanent either. Add a separately running program to a product later and the question comes back. What gets asked at that moment is the same thing: which record does the gate open onto, and which of its fields cross. The question is not asked once and closed; every new program asks it again.
One more area sits outside this article. Building a handover point to an outside system, what happens when the far side does not answer, and keeping one document from going twice belong elsewhere; we set out the rules for documents crossing to the official side in the article on how an e-invoicing connection works.
That leaves one question to settle before any code exists. Which program, running outside your own application, will touch that record? You already know the answer, and the first session of a system architecture engagement is where we put that question on the table.
