What exactly is an API?

I saw this definition of an API and was wondering if it was incorrect. API = Application Programmer Interface - isn't an API the contract? in other words, the menu in the example below, and not the waiter as it states.

"Imagine you are sitting in a restaurant and have selected your order. The menu outlines a list of food items, and the corresponding meals are prepared in the kitchen. Your waiter is the link between you and the kitchen, who communicates your order to the kitchen and returns the food back to you. This communication is similar to how APIs work. An API is analogous to a waiter, as it communicates a request from one device to another, and returns the response back to the first device.

The menu in the example is the API documentation. In a restaurant, if you order a food item which does not exist on the menu, the waiter will inform you that it is an invalid choice and will be incapable of delivering the food item. Similarly, each API has documentation that outlines the requests you are allowed to make, and the type of response you should expect to receive. If you try to make an invalid request, you will come across an error."

The example says

The menu in the example is the API documentation.

But your idea is that the API is the menu, which yes, is in conflict with the example.

I think most people would describe an API as a piece of software which acts as a standardized interface between two pieces of software. Every API has documentation (or it certainly should), but I don't think people would describe the API as the documentation for that standardized interface. I suppose you could do that, but I think you would be in a minority.

However. It's true that people commonly describe the huge document which describes all of the classes and methods and so on in the Java language as "The API Documentation" and indeed it's been officially named that since forever. But then the Java language isn't really what's being described by the quote which you posted. Java isn't an "API" in that sense.

In other words, we have two different concepts being described by the term "API", so you can't ask what exactly is an API.

APIs and SPIs (Systems Programming Interfaces) are much older than Java. In fact, I would mark their origins as the first implementations of common code made to avoid having to re-invent common functions and that pre-dates even operating systems.

A proper API marks the boundary between what the application programmer creates and what pre-coded functionality provides, although internal APIs are not uncommon these days.

In fact, I would be so bold as to say that a true API is not code at all, especially since I've worked with systems that pre-dated formal interface coding mechanisms such as Java Interfaces and the only way of accessing the external functionality was to follow the documentation.

A typical Java API these days would generally consist of an interface library and be paired with one or more implementations. For example, the JEE APIs for things like servlets. But the interface definition alone is not sufficient to make it a true API. Documentation is essential. High-level languages are often self-documenting, but that's no excuse when we have tools like JavaDoc to help us go the extra mile and fill in the fine points that just looking at a method prototype can give us.

I think a lot of blur came in with Microsoft's OLE, where the interface was essentially all you had. Java Interfaces and C/C++ header files likewise make the API seem like it's just code.

But on an IBM mainframe, you could terminate a program by loading a general-purpose register with a return code and issuing an SVC (Supervisor Call) instruction. This is a classic SPI call and the only way to know which register to load was to look at the documentation in the IBM System Services and Supervisor Calls manual.

Paul Clapham wrote:The example says

The menu in the example is the API documentation.

But your idea is that the API is the menu, which yes, is in conflict with the example.

I think most people would describe an API as a piece of software which acts as a standardized interface between two pieces of software.

I used to suppress the urge to correct someone when they would refer to the Springboot implementation as "the API", or they would say, "write an API to implement the interface..." .
I still think API is an abstract entity, the contract.

Tim Holloway wrote: API is not code at all

This is what I believe. It is at the boundary between two systems.

Here's what Wikipedia has to say about it:

Wikipedia wrote:An application programming interface (API) is a connection between computers or between computer programs. It is a type of software interface, offering a service to other pieces of software.[1] A document or standard that describes how to build such a connection or interface is called an API specification. A computer system that meets this standard is said to implement or expose an API. The term API may refer either to the specification or to the implementation.

Wikipedia, later, wrote:The term API is often used to refer to web APIs,[2] which allow communication between computers that are joined by the internet. There are also APIs for programming languages, software libraries, computer operating systems, and computer hardware. APIs originated in the 1940s, though the term did not emerge until the 1960s and 70s.

So here we have Wikipedia describing API as software interface and then, later, API as documentation, explicitly mentioning that it may be either. You can see that people have been using the term for 60-ish years now, which is a large number of generations of computing, and that it has evolved over time to mean different things.

Paul Clapham wrote:... it has evolved over time to mean different things.

Which is also true of a lot of other computer terms.

The second Wikipedia quote does not differ from the first quote, it merely indicates that an API doesn't require direct code-to-code contact on a single system or in a single address space.

To expand on the "dates to the 1940s", as I mentioned, the first APIs were things like pre-punched decks of punched cards containing library functions. You'd stuff a copy of the desired library into your application program deck and then invoke that logic by jumping/calling from your own application code. The library deck might be a mathematical function or an I/O service, to name two common examples,  As systems evolved, linkage editor programs were developed to make the connections easier and eventually, the libraries were pulled from persistent storage (e. g., disk). And we added things like system calls when OS's became common, and shared in-memory libraries, etc.

Not all computers back then were punched-card based, but paper-tape systems could likewise splice in subroutines with aid of a razor blade and adhesive tape. I don't know if magnetic tape systems were ever employed that way or not. Splicing physical magtape is not for the faint of heart, but a simple utility program could produce a new tape based on a concatenation of several source tapes.

Tim Holloway wrote:

Paul Clapham wrote:... it has evolved over time to mean different things.

Which is also true of a lot of other computer terms.

It's true of many words in the English language. If for example you're looking for the meaning of the word "key" and you want THE meaning then you're on a fool's errand.

Paul Clapham wrote:

Tim Holloway wrote:

Paul Clapham wrote:... it has evolved over time to mean different things.

Which is also true of a lot of other computer terms.

It's true of many words in the English language.

But we are not looking at historical definitions in the case of "what is an API?".
What exactly is an API in the systems and languages we work with.

How will you draw the boundary between the API and the implementation?
Are Springboot implementation methods the API?

Anil Philip wrote:But we are not looking at historical definitions in the case of "what is an API?".
What exactly is an API in the systems and languages we work with.

How will you draw the boundary between the API and the implementation?
Are Springboot implementation methods the API?

We were in fact looking at historical definitions. If you're asking for an "exact" definition of a thing then you can't turn around and exclude some versions of the thing.

As for drawing a boundary between the API and the implementation, it seems like you've decided in advance that the API and the implementation are two different things. I think we've already established that people use the term "API" to describe both the system and its documentation.

Your original post was on the right path.

I think of APIs and boundaries like this ...
An API is a contract describing how one software unit talks to another; with one side being the contract owner and the other being the consumer.  The API does not give any hint of the implementation of either side.  An API is not a document, although it can be represented with a document such as an OpenAPI document.

A boundary is separation of responsibility or ownership.

The API is the crossing point where data moves across that boundary.

Ron McLeod wrote:Your original post was on the right path.

I think of APIs and boundaries like this ...
An API is a contract describing how one software unit talks to another; with one side being the contract owner and the other being the consumer.  The API does not give any hint of the implementation of either side.  An API is not a document, although it can be represented with a document such as an OpenAPI document.

A boundary is separation of responsibility or ownership.

The API is the crossing point where data moves across that boundary.

I completely agree with this.
Another point to note; If API can be the implementation too, then why is the word "interface"  in the expansion of the acronym?
Wikipedia is not always right but then, I don't think there's any authority for this question.
When people say, "write an API", It should mean, 'design the interface'. Writing the implementation should be a separate activity.

Anil Philip wrote:
When people say, "write an API", It should mean, 'design the interface'. Writing the implementation should be a separate activity.

I concur. An API generally means that the implementation side is a "black box". If the internals of the implementation side are known and accessible to the invoker, then you no longer have an interface (you usually have a mess).

In Java, an API is generally defined via an Interface. In C/C++, an API is generally defined in a header file. Not all languages allow for separation between prototypes and actual methods, however. Python falls into that category. In the case of Python, you typically have documentation of the external classes (if any) and the method/function calls, and the internals are often only as invisible as the directories that the implementation code lives in.

But I use Python APIs all the time.

The first 10 minutes of this Devoxx talk by Mario Fusco gives a good explanation of an API: Let's make a contract: the art of designing a Java API by Mario Fusco

Ron McLeod wrote:The first 10 minutes of this Devoxx talk by Mario Fusco

thanks.  It is preferable the Wikipedia should be corrected so as to not lead people astray.