Is API exactly the same as header file?

Question

I am trying to understand the difference between an Application Programming Interface and a Library and I stumbled upon this question:

https://stackoverflow.com/questions/3678665/is-there-still-a-difference-between-a-library-and-an-api

And according to one of the answers:

A library contains re-usable chunks of code (a software program).

These re-usable codes of library is linked to your program through APIs (Application Programming Interfaces). That is, this API is an interface to library through which re-usable codes are linked to your application program. In simple term it can be said that an API is an interface between two software programs which facilitates the interaction between them.

For example, in procedural languages like C, the library math.c contains the implementations of mathematical function, such as sqrt, exp, log etc. It contains the definition of all these functions.

These function can be referenced by using the API math.h which describes and prescribes the expected behavior.

That being said, an API is a specification (math.h explains about all the functions it provides, their arguments and data they return etc.) and a library is an implementation (math.c contains all the definitions of these functions).

Stating that the C header file math.h is an API, while math.c is a library.

So therefore, when we say "API", we mean "header file"? Is API exactly the same as header file?

Answer 1

Strictly speaking, the term API in the literal sense is not a physical artefact - i.e. it's not a source code file, library, binary or service.

The literal form of an API is an agreed set of rules, essentially a 'contract' describing the external surface area or boundary between your own code and whichever service/library/binary your code is using.

Consider the real-world concept of an interface in a banal scenario such as telephone pizza ordering - your API to a pizza restaurant would be the information written on their menu, which describes everything available to order, a telephone number to call, the prices, and information on what to expect such as delivery time or accepted payment methods.

You can pick up any telephone handset and it'll work the same way; furthermore, any member of staff working at the restaurant will be familiar with the menu and will all handle your call in exactly the same way, get you the same pizza delivered in the same amount of time, charge you the same amount of money, etc.

Physically you will be interacting with the telephone handset and verbally you'll be interacting with the staff member, yet neither are part of the pizza restaurant API because those are all interchangable with other handsets and other staff members, who will all operate in the same way by following the API contract (i.e. the same phone number, the same menu information which specifies how to order).

The same underlying principle is essentially considered (in this case) with C libraries -- your vendor has created an implementation as part of their compiler called <math.h>, which is guaranteed to follow all of the rules in the ISO C standard; the C standard also specifies things which usually won't be in a header file but are part of the API, such as preconditions, postconditions, and the behaviour offered by those functions.

Physically, your code would be using that vendor's implementation, but conceptually the API you are using is formalised in the ISO standard document; your code could use any other vendor's (standard-conforming) implementation and you'll be guaranteed by the ISO standard that it will work in exactly the same way.

Answer 2

The .h/.c analogy is just an example. The API is a means to access functionality (of a library). Think of a literal library, a place that has a lot of books from which you can pick some to take home and bring back at a later time. The library would be the building with the books.

Now, there is a procedure you would need to follow in order to get to those books. First you would need a membership, show your id and all. Then you get a nice card, perhaps with a bar code or a chip on it. Then you would go to a catalog that tells you where the books are you may be interested in. Once you pulled them from the shelf you bring them to the counter and hand over your card. The person registers the books to your name and gives you back your card and you go home with the books.

All these formalities to finally get those books would be the API. In order to use the library you would first need to learn the API and once you understand that, you know how to use that library, that is your access to it.

Answer 3

Consider this counterexample:

You have a file named math.h that contains:

double sin(double x);

Then the file math.c implements this function.

Now you do a simple change to math.h:

double dblsin(double x);
#define sin dblsin

Did your API change? I'd say mostly not, although it's very ugly to use preprocessor defines to change a function name, and it could have nasty side-effects for example in functions that use sin as a local variable or parameter name, especially if there's another local variable or parameter named dblsin.

But you header file did change even if the API didn't.

The header file is something that describes the API. However, what the actual API is, is in my opinion more abstract.

It's also possible to imagine cases where the header file doesn't change, but the API does change a lot, at least if the header file contains no comments that describe how it must be used.

Answer 4

In short

The term API covers at the same time an interface implementation (for the code to use) and an interface specification (for the humans to understand).

While the API specification is abstract and independent of any programming language, the API implementation is language/middleware specific. In C in particular, there is some overlap between a header and an API, but you can have parts of a header that don't belong to the API, and conversely, you can have parts of an API that are not defined in a header.

More arguments

Is there a definition of API?

There is no authoritative definition of what an API is. But IEEE's SWEBOK provides a good start, as it is an technical report endorsed by the international standard organisation (ISO):

An application programming interface (API) is the set of signatures that are exported and available to the users of a library or a framework to write their applications. Besides signatures, an API should always include statements about the program’s effects and/or behaviors (i.e., its semantics).

The case of C and its headers

In C, any public symbols may be "exported" without necessarily having to be in a header. A non static function defined in some compilation unit will be exported to the linker even if it's not declared in some header.

Such element could be used by any other modules, provided they know how to use the symbol (e.g. hand-crafted assembler if the parameters and parameter passing convention is known, or independent C compilation unit that just declares the same function as external).

So, the API is defined independently of the header. But in practice, in C and some other languages, a header is the easiest and less error-prone manner to define once the API and make it available to other compilation units. Because it allows to use the same declaration on the "exporting" and "importing" side.

API specification vs. API implementation

Until now I only addressed the implementation of the API (with or without headers in C, but other languages use different techniques to export and import APIs.

Such an API implementation is of little use without an API specification which explains how to use the elements and what their effects are. The specification explains exactly this. For an obvious function like sin() the name of the function is almost already its specification, but there are lots of other APIs that are less obvious.

Sometimes, e.g. for WebAPI, the API is only defined by a specification: no header defines how to structure the API call over http. You have to know which server to send what request to get the results defined in the API specifications. On the other side, other distributed technologies rely on special Interface Definition Languages used by middleware to connect heterogeneous and remote system components.